Software Catalog in Harness IDP provides a comprehensive framework for defining and managing software entities, including APIs. Here’s a guideline to add API specifications, based on the Backstage descriptor format:
The type of API specs could be added in IDP.
openapi - An API definition in YAML or JSON format based on the OpenAPI version 2 or version 3 spec.
asyncapi - An API definition based on the AsyncAPI spec.
More detials on descriptor format for API's could be found in the refernce docs
Example for different use cases
Note that to be able to read from targets that are outside of the normal integration points such as
github.com, you'll need to explicitly allow it by adding an entry in the URL Allow List under Admin
Import API spec for all API defined in openapi spec
description: The official CE NEXTGEN service REST APIs
In the above example we import all the API specs in
json format as a
$text embedding, and it's a suggested hack to import multiple APIs in openapi format.
Import API spec for a single API defined in openapi spec in swaggger
description: The petstore API
- url: https://github.com/swagger-api/swagger-petstore
title: GitHub Repo
- url: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml
title: API Spec
Define API spec for a single API openapi format and import the same
description: Retrieve artist details
title: Artist API
- url: http://artist.spotify.net/v1
summary: List all artists
Steps to add the API as an entity.
- Save the YAML, created following the steps above, in your git repository.
- Follow the steps mentioned to register a software compenent, to add your API docs to IDP.