Skip to main content

How to Add API Docs

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.

  1. openapi - An API definition in YAML or JSON format based on the OpenAPI version 2 or version 3 spec.

  2. asyncapi - An API definition based on the AsyncAPI specification.

  3. graphql - An API definition based on GraphQL schemas for consuming GraphQL based APIs.

  4. grpc - An API definition based on Protocol Buffers to use with gRPC.

More details on descriptor format for API's could be found below in the references.

Example for different use cases​

info

Note that to be able to read from targets that are outside 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​

apiVersion: harness.io/v1
kind: API
type: openapi
identifier: cenextgen
name: cenextgen
owner: johndoe
spec:
  lifecycle: production
  definition:
    $text: https://github.com/OAI/OpenAPI-Specification/blob/main/examples/v2.0/json/api-with-examples.json
metadata:
  description: The official CE NEXTGEN service REST APIs
info

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.

The above-mentioned catalog-info.yaml when registered in the catalog would display all the APIs in the following format.

Import API spec for a single API defined in openapi spec in swaggger​

apiVersion: harness.io/v1
kind: API
type: openapi
identifier: petstore
name: petstore
owner: Harness_Partners
spec:
  lifecycle: dev
  definition:
    $text: ./petstore.oas.yaml
metadata:
  description: The petstore API
  links:
    - url: https://github.com/swagger-api/swagger-petstore
      title: GitHub Repo
      icon: github
    - url: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml
      title: API Spec
      icon: code
  tags:
    - store
    - rest

The above-mentioned catalog-info.yaml when registered in the catalog would display all the APIs in the following format.

Define API spec for a single API openapi format and import the same​

apiVersion: harness.io/v1
kind: API
type: openapi
identifier: artistapi
name: artistapi
owner: artist-relations-team
spec:
  lifecycle: production
  definition: |
    openapi: "3.0.0"
    info:
      version: 1.0.0
      title: Artist API
      license:
        name: MIT
    servers:
      - url: http://artist.spotify.net/v1
    paths:
      /artists:
        get:
          summary: List all artists
    ...
metadata:
  description: Retrieve artist details

The above-mentioned catalog-info.yaml when registered in the catalog would display all the APIs in the following format.

Creating an API entity​

There are two ways to add and create a new API entity in your catalog:

  • Create an entity via the Harness IDP UI: Use the Harness UI to create entities directly—no YAML required. This method offers a streamlined, code-free experience for adding entities.
  • Create an entity using your catalog YAML: You can still create entities using your existing catalog YAML files. Harness will automatically convert legacy Backstage YAML into the new Harness Catalog Entity Model and register the corresponding entity.

Defining an API Entity​

You can refer to the entity definition format here. Here's the common envelope:

  1. apiVersion: With IDP 2.0, we've introduced a Harness-native entity schema. As part of this change, all entities now use an apiVersion prefixed with harness.io/.
  2. kind: The kind field defines the high-level type of entity being described in the YAML file. For API, kind is API.
  3. identifier: The identifier field is a unique, machine-readable reference for the entity. It serves as the primary key for identifying and interacting with the entity.
  4. name: The name field represents the display name of the entity shown in the UI.
  5. type: The type field represents the type of entity (e.g., website, service, library, API, etc). The kind and type fields together define entity behavior and should always appear together.
  6. projectIdentifier: In IDP 2.0, legacy System entities are now mapped to Harness Projects. Thus the projectIdentifier field indicates which project the entity belongs to.
  7. orgIdentifier: In IDP 2.0, legacy Domain entities are now mapped to Harness Orgs. Thus the field orgIdentifier indicates which Org the entity belongs to.
  8. owner: The owner field indicates the owner of that entity and maps to Harness Users or User Groups depending on the scope.
  9. metadata: A container for auxiliary data that is not part of the entity’s specification. Additional metadata helps enhance platform-level processing or categorization
  10. spec: Defines the actual specification data that describes the entity. This is the core configuration and varies depending on the kind.

API Specification​

Kind: API​

An API describes an interface that can be exposed by a component. APIs can be defined using formats such as OpenAPI, AsyncAPI, GraphQL, gRPC, or others.

Entity Structure​

All the fields mentioned below are the mandatory parameters required to define an API:

FieldValue
apiVersionharness.io/v1
kindAPI
typeYou can find out more about the type key here.
spec.lifecycleYou can find out more about the lifecycle key here.
spec.definitionYou can find out more about the definition key here.

type Definition​

The type of the API definition as a string (e.g., openapi):

  1. openapi – A definition in YAML or JSON based on OpenAPI v2 or v3.
  2. asyncapi – A definition based on the AsyncAPI specification.
  3. graphql – A definition using GraphQL schemas.
  4. grpc – A definition based on Protocol Buffers for use with gRPC.

Example YAML​

apiVersion: harness.io/v1
kind: API
type: openapi
identifier: petstore
name: petstore
owner: Harness_Partners
spec:
  lifecycle: dev
  definition:
    $text: ./petstore.oas.yaml
metadata:
  description: The petstore API
  links:
    - url: https://github.com/swagger-api/swagger-petstore
      title: GitHub Repo
      icon: github
    - url: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml
      title: API Spec
      icon: code
  tags:
    - store
    - rest

Substitutions in Descriptor​

  1. Supports $text, $json, $yaml for embedding external content.
  2. Useful for loading API definitions from external sources.

Example​

apiVersion: harness.io/v1
kind: API
type: openapi
identifier: petstore
name: petstore
owner: Harness_Partners
spec:
  lifecycle: dev
  definition:
    $text: ./petstore.oas.yaml
metadata:
  description: The petstore API
  links:
    - url: https://github.com/swagger-api/swagger-petstore
      title: GitHub Repo
      icon: github
    - url: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml
      title: API Spec
      icon: code
  tags:
    - store
    - rest

gRPC Docs​

You can render gRPC documentation by using the protoc-gen-doc plugin, which contains ApiDefinitionWidgets for grpc-docsto enable Swagger UI for gRPC APIs.

JSON Format​

info

You can render gRPC documentation when the type is set to grpc-doc or grpc and the definition is provided in JSON format.

Type: grpc​

##Example
apiVersion: harness.io/v1
kind: API
type: grpc
identifier: grpcdocstest1
name: grpcdocstest1
owner: group:engineering
spec:
  lifecycle: production
  definition:
    $text: https://github.com/pseudomuto/protoc-gen-doc/blob/master/examples/doc/example.json

Rendered Output for JSON Format​

Type: grpc-docs​

Example catalog-info.yaml

apiVersion: harness.io/v1
kind: API
type: grpc-docs
identifier: grpcdocstest
name: grpcdocstest
owner: group:engineering
spec:
  lifecycle: production
  definition:
    $text: https://github.com/pseudomuto/protoc-gen-doc/blob/master/examples/doc/example.json

Rendered Output for JSON Format​

proto file Format​

## Example
apiVersion: harness.io/v1
kind: API
type: grpc
identifier: helloworldunaryapi
name: helloworldunaryapi
owner: zalopay-oss
spec:
  lifecycle: production
  files:
    - file_name: helloworld.proto
      file_path: examples/unary/helloworld.proto
      url: https://github.com/zalopay-oss/backstage-grpc-playground/blob/main/examples/unary/helloworld.proto
  definition:
    $text: https://github.com/zalopay-oss/backstage-grpc-playground/blob/main/examples/unary/helloworld.proto
  targets:
    dev:
      host: 0.0.0.0
      port: 8084
metadata:
  description: helloworld unary gRPC

Rendered Output for proto file​