Add API Documentation

Learn how to add and manage API documentation in various formats to your Software Catalog.

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.

For type: openapi entities, Harness IDP also automatically extracts individual endpoints from the spec and makes them available for enrichment with custom metadata. See API endpoint extraction and enrichment.

---

Supported API types

Harness IDP supports the following API specification formats:

1. OpenAPI - API definitions in YAML or JSON format based on OpenAPI version 2 or version 3

2. AsyncAPI - API definitions based on the AsyncAPI specification

3. GraphQL - API definitions based on GraphQL schemas

4. gRPC - API definitions based on Protocol Buffers for use with gRPC

---

Before you begin

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

Steps:

1. Navigate to Configure → URL Allow List in your IDP portal

2. Add the domains or URLs where your API specifications are hosted

3. 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

In the above example we import all the API specs in json format as a $text embedding, and it is 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.

In IDP, API entity creation 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.

---

Create 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.

Define an API entity

Go to the entity definition format to review the common envelope:

1. apiVersion: With IDP 2.0, we have 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:

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):

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: 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

Use a substitution placeholder in spec.definition to reference a Git-hosted spec rather than embedding it inline. The placeholder tells IDP what file format to expect when it fetches the content:

Placeholder	Use when the spec file is
$yaml	A YAML file (.yaml or .yml)
$json	A JSON file (.json)
$text	Any other text format

apiVersion: harness.io/v1
kind: API
type: openapi
identifier: payment-service
name: payment-service
owner: payments-team
spec:
  lifecycle: production
  definition:
    # Replace $yaml with $json or $text to match your spec file format.
    # Only Git-based URLs (GitHub, GitLab, Bitbucket, Azure Repo) are supported here.
    # For public HTTP URLs, put the URL directly as the definition value. No $ prefix.
    $yaml: https://github.com/your-org/your-repo/blob/main/openapi.yaml
metadata:
  description: Payment service API
  annotations:
    # Required for private repositories so IDP resolves the correct Git credentials.
    # Remove this annotation if your repository is public.
    backstage.io/source-location: url:https://github.com/your-org/your-repo/tree/main

Placeholders in Harness IDP support only Git-based URLs (GitHub, GitLab, Bitbucket, Azure Repo). Arbitrary public HTTP URLs do not work in placeholder syntax. For specs hosted at a non-Git public URL, put the URL directly as the spec.definition value without a $ prefix. Add the domain to Configure → URL Allow List if you want the spec to render in the UI.

For private Git repositories, you also need a Git Integration configured at Configure → Git Integrations and a backstage.io/source-location annotation pointing to the repository root. For public Git repositories, the Git Integration alone is sufficient. See API endpoint extraction and enrichment for setup steps.

---

Endpoint extraction and enrichment

When your API entity has type: openapi, Harness IDP automatically extracts endpoints from the spec and stores a trimmed, operable representation in Ingested Properties under metadata.apis. You can enrich individual endpoints with custom metadata from external tools using the Catalog Custom Properties API.

See API endpoint extraction and enrichment.

---

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

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 <a href="#example" id="example"></a>
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