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:

- name: Human Readable Name
type: runbook
description: Optional Description

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

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

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:

- name: My Spec
url: ./docs/my-openapi-spec.yaml

Git-Driven Markdown Docs

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

Embed Dashboards

Cortex supports embedding charts directly into the Catalog for quick access, making the Catalog a single pane of glass for your architecture.

- type: datadog | grafana | newrelic

The type field is an enum of three types. This field is used when generating screenshots for certain Slack integration points. If you do not plan to use this feature, feel free to choose any type as it's ignored entirely when embedding in the catalog.

The url field is the src value for the iframe embed generated by your dashboard tool.


If using Grafana, note that you can only embed charts, not dashboards. If you're seeing errors in your Grafana embeds, make sure your Grafana instance has embeds enabled.