Skip to main content

External Documentation

Cortex is your source of truth to external documentation - instead of digging through your wikis, you can aggregate links and API documentation into one easily accessible place.

Documentation is easily accessible through the Catalog, on the homepage for each service.

You can easily add links to docs, runbooks, tech specs, dashboards, and more.

The Service Descriptors a list of Link objects:

x-cortex-links:
  - name: Human Readable Name
    type: runbook
    url: https://cortex.io
    description: Optional Description

The value of type can be anything you want – examples include:

  • runbook
  • documentation
  • logs
  • dashboard
  • metrics
  • healthcheck
tip

You can look up links easily using our Slackbot!

Swagger/OpenAPI Documentation​

API documentation is a special case. Cortex supports displaying Swagger/OpenAPI specs for each service, in the "API Explorer" tab. There are a few ways of adding API specs to Cortex

Service Descriptor​

You can use your Service Descriptor file as an OpenAPI spec file. Since the Service Descriptor file extends the OpenAPI spec, you can simply implement the spec directly in this file.

Existing Specs​

If you have existing or external specs you want to display in the API explorer (e.g. from Swagger Hub, GitHub Raw URL, etc), simply add a URL to the spec file (JSON or YAML) as an x-cortex-link, with type openapi. The spec will then automatically show up in the API Explorer.

If you have specs checked into your service's Git repository, you can embed it by adding it as a relative URL with type openapi, like:

x-cortex-link:
  - name: My Spec
    type: OPENAPI
    url: ./docs/my-openapi-spec.yaml

Embedded Docs​

Cortex automatically embeds markdown files from the docs folder of your repo in the Catalog. These docs show up under the "Docs" tab.