diff --git a/plugins/api-docs/README.md b/plugins/api-docs/README.md index 7ea87004c3..db78b60373 100644 --- a/plugins/api-docs/README.md +++ b/plugins/api-docs/README.md @@ -3,7 +3,25 @@ WORK IN PROGRESS This is an extension for the catalog plugin that provides components to discover and display API entities. +APIs define the interface between components, see the [system model](https://backstage.io/docs/features/software-catalog/system-model) for details. +They are defined in machine readable formats and provide a human readable documentation. + +The plugin provides a standalone list of APIs, as well as an integration into the API tab of a catalog entity. + +![Standalone API list](./docs/api_list.png) +![OpenAPI Definition](./docs/openapi_definition.png) +![Integration into components](./docs/entity_tab_api.png) + +Right now, the following API formats are supported: + +- [OpenAPI](https://swagger.io/specification/) 2 & 3, +- [AsyncAPI](https://www.asyncapi.com/docs/specifications/latest/), + +Other formats are displayed as plain text, but this can easily be extented. + +To fill the catalog with APIs, [provide entities of kind API](https://backstage.io/docs/features/software-catalog/descriptor-format#kind-api). +To link that an component implements an API, see [`implementsApis` property on components](https://backstage.io/docs/features/software-catalog/descriptor-format#specimplementsapis-optional). ## Links -- (The Backstage homepage)[https://backstage.io] +- [The Backstage homepage](https://backstage.io) diff --git a/plugins/api-docs/docs/api_list.png b/plugins/api-docs/docs/api_list.png new file mode 100644 index 0000000000..abc948b3c6 Binary files /dev/null and b/plugins/api-docs/docs/api_list.png differ diff --git a/plugins/api-docs/docs/entity_tab_api.png b/plugins/api-docs/docs/entity_tab_api.png new file mode 100644 index 0000000000..1ab9de02cd Binary files /dev/null and b/plugins/api-docs/docs/entity_tab_api.png differ diff --git a/plugins/api-docs/docs/openapi_definition.png b/plugins/api-docs/docs/openapi_definition.png new file mode 100644 index 0000000000..af04946b19 Binary files /dev/null and b/plugins/api-docs/docs/openapi_definition.png differ diff --git a/plugins/auth-backend/README.md b/plugins/auth-backend/README.md index 4bbbb7246b..29bec3e694 100644 --- a/plugins/auth-backend/README.md +++ b/plugins/auth-backend/README.md @@ -88,4 +88,4 @@ To try out SAML, you can use the mock identity provider: ## Links -- (The Backstage homepage)[https://backstage.io] +- [The Backstage homepage](https://backstage.io) diff --git a/plugins/catalog-backend/README.md b/plugins/catalog-backend/README.md index 246cd83d56..7c52dfad72 100644 --- a/plugins/catalog-backend/README.md +++ b/plugins/catalog-backend/README.md @@ -30,5 +30,5 @@ This will launch the full example backend and populate its catalog with some moc ## Links -- (Frontend part of the plugin)[https://github.com/spotify/backstage/tree/master/plugins/catalog] -- (The Backstage homepage)[https://backstage.io] +- [Frontend part of the plugin](https://github.com/spotify/backstage/tree/master/plugins/catalog) +- [The Backstage homepage](https://backstage.io) diff --git a/plugins/catalog/README.md b/plugins/catalog/README.md index 52bbd0d0c3..cff632cb24 100644 --- a/plugins/catalog/README.md +++ b/plugins/catalog/README.md @@ -9,5 +9,5 @@ supply the base views to show and manage them. ## Links -- (Backend part of the plugin)[https://github.com/spotify/backstage/tree/master/plugins/catalog-backend] -- (The Backstage homepage)[https://backstage.io] +- [Backend part of the plugin](https://github.com/spotify/backstage/tree/master/plugins/catalog-backend) +- [The Backstage homepage](https://backstage.io) diff --git a/plugins/identity-backend/README.md b/plugins/identity-backend/README.md index 7d97bb5f6b..c95fed0698 100644 --- a/plugins/identity-backend/README.md +++ b/plugins/identity-backend/README.md @@ -8,4 +8,4 @@ It responds to identity requests from the frontend. ## Links -- (The Backstage homepage)[https://backstage.io] +- [The Backstage homepage](https://backstage.io) diff --git a/plugins/rollbar-backend/README.md b/plugins/rollbar-backend/README.md index 8cd08abed3..c221dfd23b 100644 --- a/plugins/rollbar-backend/README.md +++ b/plugins/rollbar-backend/README.md @@ -19,5 +19,5 @@ access account token._ ## Links -- (Frontend part of the plugin)[https://github.com/spotify/backstage/tree/master/plugins/rollbar] -- (The Backstage homepage)[https://backstage.io] +- [Frontend part of the plugin](https://github.com/spotify/backstage/tree/master/plugins/rollbar) +- [The Backstage homepage](https://backstage.io) diff --git a/plugins/rollbar/README.md b/plugins/rollbar/README.md index d0cfae00cc..94ef38b43a 100644 --- a/plugins/rollbar/README.md +++ b/plugins/rollbar/README.md @@ -52,5 +52,5 @@ builder.add( ## Links -- (Backend part of the plugin)[https://github.com/spotify/backstage/tree/master/plugins/rollbar-backend] -- (The Backstage homepage)[https://backstage.io] +- [Backend part of the plugin](https://github.com/spotify/backstage/tree/master/plugins/rollbar-backend) +- [The Backstage homepage](https://backstage.io) diff --git a/plugins/scaffolder/README.md b/plugins/scaffolder/README.md index 5893ee86ba..a356cb8ec9 100644 --- a/plugins/scaffolder/README.md +++ b/plugins/scaffolder/README.md @@ -6,5 +6,5 @@ This is the frontend part of the default scaffolder plugin. ## Links -- (Backend part of the plugin)[https://github.com/spotify/backstage/tree/master/plugins/scaffolder-backend] -- (The Backstage homepage)[https://backstage.io] +- [Backend part of the plugin](https://github.com/spotify/backstage/tree/master/plugins/scaffolder-backend) +- [The Backstage homepage](https://backstage.io) diff --git a/plugins/techdocs-backend/README.md b/plugins/techdocs-backend/README.md index ad98d07f95..a377d2e6c7 100644 --- a/plugins/techdocs-backend/README.md +++ b/plugins/techdocs-backend/README.md @@ -18,5 +18,5 @@ yarn start ## Links -- (Frontend part of the plugin)[https://github.com/spotify/backstage/tree/master/plugins/techdocs] -- (The Backstage homepage)[https://backstage.io] +- [Frontend part of the plugin](https://github.com/spotify/backstage/tree/master/plugins/techdocs) +- [The Backstage homepage](https://backstage.io)