Add API Documentation

Last updated on May 14, 2026

The Harness IDP Software Catalog provides comprehensive support for defining and managing API entities. This guide shows you how to add API specifications in various formats to your catalog.

Supported API Types

Harness IDP supports the following API specification formats:

OpenAPI - API definitions in YAML or JSON format based on OpenAPI version 2 or version 3
AsyncAPI - API definitions based on the AsyncAPI specification
GraphQL - API definitions based on GraphQL schemas
gRPC - API definitions based on Protocol Buffers for use with gRPC

Prerequisites

To fetch API specifications from external sources, you must configure the URL Allow List.

Steps:

Navigate to Configure → URL Allow List in your IDP portal
Add the domains or URLs where your API specifications are hosted
Use wildcards (e.g., *.github.com) to allow multiple subdomains

URL Allow List

Backend URL Allow List

By default, Harness IDP restricts backend fetching and only allows requests to explicitly allowed domains.

To enable access:

Go to Configure → URL Allow List
Add full domains or use wildcards (e.g., *.apis.com) for subdomains
List specific paths with trailing slashes (e.g., /exampledir/ allows /exampledir/example)

Ensure your API spec host or path is included in this list for successful import.

Add API Entities

OpenAPI Specifications

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.

Backend URL Allow List

By default, Backstage restricts backend fetching and only allows requests to public APIs defined in catalog-info.yaml files if the domains are explicitly allowed.

To enable access:

Go to your IDP portal and navigate to Configure → URL Allow List.
Add full domains or use wildcards (e.g., *.apis.com) to allow subdomains.
You can also list specific paths. Subdirectories are supported using a trailing slash (e.g., /exampledir/ allows /exampledir/example).

Make sure the host or path for your OpenAPI spec is included in this list to allow successful API documentation import.

caution

In IDP 2.0, API entity creation now supports OpenAPI specifications referenced via both absolute URLs (e.g., https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.yaml) and relative paths (e.g., ./openapi.yaml) in the spec.definition.$text field. These paths are interpreted relative to the location specified by the backstage.io/managed-by-location annotation. This typically aligns with the path of your entity YAML file. When not explicitly set, managed-by-location is automatically derived from the backstage.io/source-location annotation, ensuring correct resolution even for inline or centrally managed entities.

For external URLs, ensure the domain is included in the Backend URL Allow List under Configure → URL Allow List to enable proper API documentation rendering.

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 swagger

apiVersion: harness.io/v1
kind: API
type: openapi
identifier: petstore
name: petstore
owner: Harness_Partners
spec:
  lifecycle: dev
  definition:
    $text: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.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:

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/.
kind: The kind field defines the high-level type of entity being described in the YAML file. For API, kind is API.
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.
name: The name field represents the display name of the entity shown in the UI.
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.
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.
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.
owner: The owner field indicates the owner of that entity and maps to Harness Users or User Groups depending on the scope.
metadata: A container for auxiliary data that is not part of the entity’s specification. Additional metadata helps enhance platform-level processing or categorization
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:

Field	Value
`apiVersion`	harness.io/v1
`kind`	API
`type`	You can find out more about the `type` key here.
`spec.lifecycle`	You can find out more about the `lifecycle` key here.
`spec.definition`	You can find out more about the `definition` key here.

`type` Definition

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

openapi – A definition in YAML or JSON based on OpenAPI v2 or v3.
asyncapi – A definition based on the AsyncAPI specification.
graphql – A definition using GraphQL schemas.
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: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.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

Supports $text, $json, $yaml for embedding external content.
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: https://github.com/swagger-api/swagger-petstore/blob/master/src/main/resources/openapi.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-docs to 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

Supported API Types​

Prerequisites​

Add API Entities​

OpenAPI Specifications​

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

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

Creating an API entity​

Defining an API Entity​

API Specification​

Kind: API​

Entity Structure​

type Definition​

Example YAML​

Substitutions in Descriptor​

Example​

gRPC Docs​

JSON Format​

Type: grpc​

Rendered Output for JSON Format​

Type: grpc-docs​

Rendered Output for JSON Format​

proto file Format​

Rendered Output for proto file​

Supported API Types

Prerequisites

Add API Entities

OpenAPI Specifications

Import API spec for a single API defined in openapi spec in swagger

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

Creating an API entity

Defining an API Entity

API Specification

Kind: API

Entity Structure

`type` Definition

Example YAML

Substitutions in Descriptor

Example

gRPC Docs

JSON Format

Type: `grpc`

Rendered Output for JSON Format

Type: `grpc-docs`

Rendered Output for JSON Format

proto file Format

Rendered Output for proto file