API Docs

API Docs are a powerful tool for an organization to document all of the APIs exposed by their services. This can increase developer productivity tremendously. But as your organization grows, you will run into a few challenges:

• Consistency - where are the docs located? In our wiki? In a repo?
• Freshness - when were the docs last updated? Do all the /v1 APIs still work?

OpsLevel provides a centralized location for API Docs. Developers don’t have to waste time searching through different tools or asking teams for help. They can simply login to OpsLevel and view the API docs for all their services.

OpsLevel can drive keeping your API Docs up-to-date, automatically. When used alongside OpsLevel’s Git Integration, developers can track their docs in source control and OpsLevel will automatically update the displayed API Docs whenever they change. Developers can also push API Docs to OpsLevel via a REST API as part of CI so they are always up-to-date.

The Has API Docs check can help ensure that API Docs exist on all the services in your organization.

Getting API Docs into OpsLevel

Push vs Pull

First, you will have to generate an OpenAPI document file for your service, outside of OpsLevel. This usually involves adding annotations to your source code and using a tool like springdoc-openapi (for Java), apispec (for Python) or rswag (for Ruby) to automatically generate an OpenAPI document. Alternatively, you can manually write the OpenAPI document yourself.

Once you have your OpenAPI document, there are two ways to get it into OpsLevel:

• Pull flow - OpsLevel pulls API Docs from your repository
• Push flow - You push API Docs to OpsLevel via a REST API

OpsLevel recommends the Pull flow since it’s easier to automate which will result in more up-to-date API Docs. If your OpenAPI document is tracked under source control, it will automatically appear in OpsLevel! The Push flow requires an additional step of sending your docs to OpsLevel.

You should use the Pull flow if:

• You don’t have an existing API Docs process
• You don’t want to add an additional CI step to push docs to OpsLevel

You should use the Push flow if:

• You can’t track your OpenAPI file under source control
• You can setup a CI step to push your OpenAPI file to OpsLevel

Setting up the Pull Flow

To use the Pull flow, add a Git integration, if you do not already have one. Then add the OpenAPI file to the repository that is connected to your service.

By default, OpsLevel will try to pull the file from the ./swagger.json path in the repository connected to the service. You can change this default path (known as the API Docs File Path) by emailing our support team. You can view the default API Docs File Path on the Account page. Note that you need to be an Admin user to view this page.

If a repo has its OpenAPI file in a different path than the default API Docs File Path, you can change the path for that repo (more info below).

Some additional notes:

• If multiple repositories are connected to a service, OpsLevel will use the repository containing the opslevel.yml file that is managing the service. If no repository has an opslevel.yml file, OpsLevel will use the first valid repository connected to the service.
• The API Docs File Path is relative to the directory the repository is connected to the service at. If the repository is connected to the service at a different path than the root path, the API Docs File Path will be relative to that path, ex. specialDirectory/swagger.json.

Setting up the Push Flow

To use the Push flow, you will need to add an API Docs integration. Go to the integrations page and click New Integration.

Find the API Docs integration and click Add Integration.

Click Create.

Pushing API Docs

On the API Docs integration page, you will see 2 ways to send us your API docs at the bottom of the page: Using the OpsLevel CLI or using cURL. You can also copy sample commands for both.

Remember to update the service_alias in the CLI command to the alias of the service you want to send API docs for. For the cURL command, the service_alias needs to be updated in the request URL.

The webhook URL will return a response body that will differ depending on if the request succeeded or failed:

• Success - the response body will contain a result key and an optional message key in case there was a validation issue
• Error - the response body will contain an errors key which is a list of objects that contain status, title and detail keys

Viewing API Docs

Go to the service’s page in OpsLevel and click the API Docs tab.

And voila! The API Docs for that service will be displayed. You can view detailed information about an endpoint by clicking the Expand button on the right.

Expanding an endpoint will show detailed information about the request payload and the types of responses.

Clicking an endpoint will add it to the url which allows you to share a link to a specific endpoint.

You can see the “Source” of the API Docs on the right which will be either:

• A repository file, if you’re using the Pull flow
• An API Docs Integration, if you’re using the Push flow

Clicking the link will open the repository file or the API Docs Integration page in OpsLevel.

Changing the API Docs Source

It’s possible that no API Docs are displayed for the service. This can happen if:

• The repository file does not exist
• OpsLevel is looking for the wrong file path in the repository
• An API Doc has not been pushed to OpsLevel

If OpsLevel is looking for the file in the wrong place, you can change the API Docs Source by clicking the Edit button.

You’ll also be able to switch between the Pull flow (ie. File Path) and the Push flow (ie. API Docs Integration) for a given service.

Supported Formats

OpsLevel uses SwaggerUI to display API Docs defined in the OpenAPI specification, up to and including OpenAPI v3.0.x. The docs need to be defined in JSON or YAML.