feat(docs): autogenerate API documentation #27573

aramissennyeydd · 2024-11-10T14:59:46Z

Hey, I just made a Pull Request!

Addresses #26894.

This uses https://github.com/PaloAltoNetworks/docusaurus-openapi-docs to render our existing specs. The goal here is to make the OpenAPI spec the source of truth for docs + API definition. I moved the existing catalog docs into the spec and saw really nice results in the autogenerated markdown.

TODO:

Figure out a better balance of stored in git vs generated.

✔️ Checklist

A changeset describing the change and affected packages. (more info)
Added or updated documentation
Tests for new functionality and regression tests for bug fixes
Screenshots attached (for UI changes)
All your commits have a Signed-off-by line in the message. (more info)

backstage-goalie · 2024-11-10T15:00:14Z

Missing Changesets

The following package(s) are changed by this PR but do not have a changeset:

@backstage/catalog-client
@backstage/plugin-catalog-backend
@backstage/plugin-search-backend

See CONTRIBUTING.md for more information about how to add changesets.

Changed Packages

Package Name	Package Path	Changeset Bump	Current Version
@backstage/catalog-client	packages/catalog-client	none	`v1.9.1`
@backstage/plugin-catalog-backend	plugins/catalog-backend	none	`v1.31.1-next.0`
@backstage/plugin-search-backend	plugins/search-backend	none	`v1.8.3-next.0`

backstage-goalie · 2024-11-10T16:19:47Z

Thanks for the contribution!
All commits need to be DCO signed before they are reviewed. Please refer to the the DCO section in CONTRIBUTING.md or the DCO status for more info.

awanlin

This looks like a great addition to the docs @aramissennyeydd, thanks for taking this on!

Looks good over all, curious about two things:

Whats the impact on build time?
Do we need to manage the new sidebars manually?

github-actions · 2024-12-26T02:01:51Z

This PR has been automatically marked as stale because it has not had recent activity from the author. It will be closed if no further activity occurs. If the PR was closed and you want it re-opened, let us know and we'll re-open the PR so that you can continue the contribution!

.eslintrc.js

aramissennyeydd · 2024-12-30T00:46:09Z

@awanlin Sorry for the slow response here, impact on build time should be ~2 mins added, mostly from having to run the extra yarn install. I think there are security issues if we don't separate out the user generated content + hosted content. Happy to chat about this at the next SIG though :)

We will also need to manage the new sidebars semi-manually, we'd need to add the initial reference to the autogenerated file as I have here, but after that, we can just use the autogenerated one.

github-actions · 2025-01-13T00:53:58Z

This PR has been automatically marked as stale because it has not had recent activity from the author. It will be closed if no further activity occurs. If the PR was closed and you want it re-opened, let us know and we'll re-open the PR so that you can continue the contribution!

packages/catalog-client/src/schema/openapi/generated/apis/Api.client.ts

freben

Pretty cool. Tentative approval. Would love to see the result of it, but haven't had the time yet to run it locally. I see it angers lighthouse too.

packages/catalog-client/src/schema/openapi/generated/apis/Api.client.ts

aramissennyeydd · 2025-02-04T14:14:04Z

Lighthouse ended up being a CJS/MJS issue :shaking_fist, should be fixed now :)

awanlin

Let's try it out 🚀

github-actions · 2025-02-24T15:06:42Z

This PR has been automatically marked as stale because it has not had recent activity from the author. It will be closed if no further activity occurs. If the PR was closed and you want it re-opened, let us know and we'll re-open the PR so that you can continue the contribution!

Rugvip

Awesome stuff! 😁

Couple small pieces before

microsite/package.json

microsite/sidebars.js

microsite/docusaurus.config.ts

Rugvip · 2025-02-28T11:11:32Z

microsite/docusaurus.config.ts

@@ -266,7 +276,27 @@ const config: Config = {
        ratingMode: 'stars',
      },
    ],
+    [
+      'docusaurus-plugin-openapi-docs',


Ran into a minor cosmetic issue:

The double // goes away if I remove the leading / from the generated .mdx files, but perhaps there's some config somewhere to avoid the other /. Either way not a blocking issue, fine to merge without a fix for this.

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com>

Signed-off-by: Aramis Sennyey <159921952+aramissennyeydd@users.noreply.github.com>

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com>

Rugvip

Alright, let's 🎉

Thank you, awesome stuff! 😁 👍

github-actions bot added area:documentation Improvements or additions to documentation area:catalog Related to the Catalog Project Area area:microsite Changes to backstage.io labels Nov 10, 2024

aramissennyeydd force-pushed the sennyeya/docsite-openapi branch from 156c510 to ae114a7 Compare November 10, 2024 15:00

aramissennyeydd mentioned this pull request Nov 10, 2024

fix: move dependencies to peer dependencies PaloAltoNetworks/docusaurus-openapi-docs#1019

Merged

4 tasks

awanlin reviewed Nov 22, 2024

View reviewed changes

aramissennyeydd force-pushed the sennyeya/docsite-openapi branch from 704463a to 8e11767 Compare November 29, 2024 01:42

aramissennyeydd force-pushed the sennyeya/docsite-openapi branch from 33328cd to 8954557 Compare December 12, 2024 01:37

github-actions bot added search area:search labels Dec 12, 2024

github-actions bot added the stale label Dec 26, 2024

aramissennyeydd commented Dec 30, 2024

View reviewed changes

.eslintrc.js Outdated Show resolved Hide resolved

github-actions bot removed the stale label Dec 30, 2024

github-actions bot added the stale label Jan 13, 2025

aramissennyeydd removed the stale label Jan 16, 2025

aramissennyeydd commented Jan 29, 2025

View reviewed changes

packages/catalog-client/src/schema/openapi/generated/apis/Api.client.ts Outdated Show resolved Hide resolved

aramissennyeydd force-pushed the sennyeya/docsite-openapi branch from a1254c2 to 53f55db Compare January 29, 2025 03:07

aramissennyeydd marked this pull request as ready for review January 31, 2025 14:57

aramissennyeydd requested review from a team and backstage-service as code owners January 31, 2025 14:57

aramissennyeydd requested a review from freben January 31, 2025 14:57

aramissennyeydd requested a review from vinzscam January 31, 2025 14:57

freben approved these changes Feb 4, 2025

View reviewed changes

packages/catalog-client/src/schema/openapi/generated/apis/Api.client.ts Show resolved Hide resolved

github-actions bot added the domain:docs label Feb 4, 2025

awanlin approved these changes Feb 10, 2025

View reviewed changes

github-actions bot added the stale label Feb 24, 2025

Rugvip removed the stale label Feb 28, 2025

Rugvip reviewed Feb 28, 2025

View reviewed changes

Rugvip approved these changes Feb 28, 2025

View reviewed changes

aramissennyeydd and others added 9 commits February 28, 2025 09:26

feat(docs): autogenerate documentation from the API specs

b283170

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com>

update server based on schema changes

60aeb0e

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com>

fix docsite prettier

69ebbb9

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com>

Update .eslintrc.js

58164fc

Signed-off-by: Aramis Sennyey <159921952+aramissennyeydd@users.noreply.github.com>

fix comments

9022aff

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com>

update search-backend as well

8f1f5a4

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com>

yarn dedupe

26157cd

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com>

revert sidebars.js to cjs

8171eb6

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com>

fix config to support ts imports

c49e11b

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com>

aramissennyeydd force-pushed the sennyeya/docsite-openapi branch from a94996d to c49e11b Compare February 28, 2025 16:09

aramissennyeydd added 3 commits February 28, 2025 10:18

use raw releases

a5ca63d

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com>

fix links

ca11bb3

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com>

fix prettier

de1fad9

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com>

Rugvip approved these changes Mar 2, 2025

View reviewed changes

Rugvip merged commit 1ebf9f6 into backstage:master Mar 2, 2025
32 checks passed

aramissennyeydd mentioned this pull request Apr 11, 2025

🚀 Feature: Move API Reference to Separate Site + Build Process #29557

Open

2 tasks

feat(docs): autogenerate API documentation #27573

feat(docs): autogenerate API documentation #27573

Uh oh!

Conversation

aramissennyeydd commented Nov 10, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Hey, I just made a Pull Request!

✔️ Checklist

Uh oh!

backstage-goalie bot commented Nov 10, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Missing Changesets

Changed Packages

Uh oh!

backstage-goalie bot commented Nov 10, 2024

Uh oh!

awanlin left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Dec 26, 2024

Uh oh!

Uh oh!

aramissennyeydd commented Dec 30, 2024

Uh oh!

github-actions bot commented Jan 13, 2025

Uh oh!

Uh oh!

freben left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

aramissennyeydd commented Feb 4, 2025

Uh oh!

awanlin left a comment

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Feb 24, 2025

Uh oh!

Rugvip left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Rugvip Feb 28, 2025

Choose a reason for hiding this comment

Uh oh!

Rugvip left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

aramissennyeydd commented Nov 10, 2024 •

edited

Loading

backstage-goalie bot commented Nov 10, 2024 •

edited

Loading

freben left a comment •

edited

Loading