Readme for api-docs Plugin (#2041)

* docs(api-docs): add details to readme

* docs: fix wrong markdown in readme files

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)

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)

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)

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)

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)

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)

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)

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)

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)