Merge pull request #27573 from aramissennyeydd/sennyeya/docsite-openapi

feat(docs): autogenerate API documentation

docs/architecture-decisions/index.md

@@ -27,7 +27,7 @@ Records should be stored under the `architecture-decisions` directory.
 - Address and integrate feedback from the community
 - Eventually, assign a number
 - Add the path of the ADR to the microsite sidebar in
-  [`sidebars.js`](https://github.com/backstage/backstage/blob/master/microsite/sidebars.js)
+  [`sidebars.ts`](https://github.com/backstage/backstage/blob/master/microsite/sidebars.ts)
 - Add the path of the ADR to the
   [`mkdocs.yml`](https://github.com/backstage/backstage/blob/master/mkdocs.yml)
 - Merge the pull request

docs/contribute/project-structure.md

@@ -39,7 +39,7 @@ the code.
 - [`docs/`](https://github.com/backstage/backstage/tree/master/docs) - This is
   where we keep all of our documentation Markdown files. These end up on
   https://backstage.io/docs. Just keep in mind that changes to the
-  [`sidebars.js`](https://github.com/backstage/backstage/blob/master/microsite/sidebars.js)
+  [`sidebars.ts`](https://github.com/backstage/backstage/blob/master/microsite/sidebars.ts)
   file may be needed as sections are added/removed.
 
 - [`.editorconfig`](https://github.com/backstage/backstage/tree/master/.editorconfig) -

docs/openapi/generated-docs/404.md

@@ -0,0 +1,16 @@
+---
+id: 404
+title: Unable to find API docs
+sidebar_label: API
+description: Unable to find the requested API docs.
+---
+
+## API Docs Missing
+
+If you're seeing this page at backstage.io/docs, please open an issue in the main repository. Something is wrong.
+
+If you're seeing this page locally and you want to see the actual API docs for this plugin, you need to
+
+1. cd into the `microsite/` directory.
+2. run `yarn generate-openapi-docs` to generate the API docs.
+3. rerun `yarn start` to pick up the new generated docs.

docs/publishing.md

@@ -53,7 +53,7 @@ Additional steps for the main line release
   - Mention any security fixes
 - Create Release Notes PR
   - Add the release note file as [`/docs/releases/vx.y.0.md`](./releases)
-  - Add an entry to [`/microsite/sidebar.js`](https://github.com/backstage/backstage/blob/master/microsite/sidebars.js) for the release note
+  - Add an entry to [`/microsite/sidebars.ts`](https://github.com/backstage/backstage/blob/master/microsite/sidebars.ts) for the release note
   - Update the navigation bar item in [`/microsite/docusaurus.config.ts`](https://github.com/backstage/backstage/blob/master/microsite/docusaurus.config.ts) to point to the new release note
   - Finally copy the content, without the metadata header, into the description of the [`Version Packages` Pull Request](https://github.com/backstage/backstage/pulls?q=is%3Aopen+is%3Apr+in%3Atitle+%22Version+Packages)