The Open API spec support of Backstage allows users to look up and read the OpenAPI specs of services in the catalog.
Creating Open API specs is outside the scope of this documentation. Please see the Swagger OpenAPI Getting Started Guide for more information on writing OpenAPI specs.
Before starting this guide, please…
- Prepare an OpenAPI spec to use. Alternatively, you can use one of the APIs listed on APIs Guru. In the examples below, we will use the Spotify API Spec.
- Understand how entities are added to Backstage via YAML definitions. Please read the Adding Components Guide to learn more.
- Track a component in Backstage so we can add an API spec to it.
Create a YAML file called
api-info.yaml in the root of your component, alongside your code. This file will represent your API inside Backstage.
apiVersion: backstage.io/v1alpha1 kind: API metadata: name: spotify description: The official Spotify REST API spec: type: openapi lifecycle: production owner: spotify definition: $text: https://api.apis.guru/v2/specs/spotify.com/v1/swagger.yaml
API kind can take many of the normal
spec properties such as
spec.definition.$text property must point to the remote URL of your OpenAPI spec.
Note that if you are hosting your OpenAPI specs in GitHub and referencing them with the $text property, the link must point to the URL starting with
https://github.com and not
Once this YAML file is committed and available on GitHub, you can make Roadie Backstage aware of it using the catalog importer.
Copy the URL of the YAML spec on GitHub, paste it into the catalog importer at
https://your-company.roadie.so/catalog-import and click Analyze.
Review the action the importer is going to take, then press Import.
Click the name of the API to view it in Backstage.
You should also be able to view your API in the list of APIs Backstage tracks by clicking the “APIs” item in the sidebar or visiting
Now that the API is tracked in Backstage, we can associate it with a component.
catalog-info.yaml file of a component, add the
spec.providesApis property to
indicate that this component provides the
apiVersion: backstage.io/v1alpha1 kind: Component metadata: name: sample-service-2 # Other metadata and annotations omitted for brevity. spec: type: service owner: my-team lifecycle: experimental providesApis: - spotify
spec.providesAPIs must match the
metadata.name of the
API we created earlier.
A single component can provide multiple APIs.
Once this step is done correctly, we can visit the API tab of our component in Backstage to see that it provides the Spotify API.
And we can click through to the definition of that API to see the specification.