Linking API Projects

API references can be generated and included in your documentation by linking an API project in the Sideko app.

1. Create an API project by following the Getting Started guide.
2. In your documentation editor select Linked APIs➕ > 🔗 Link

3. Select the API Project and Version you would like to link and enter in the name you would like the linked API to be displayed as in the documentation.

4. 🎉 All done, you will see the generated API references when you next deploy

When linking an API to your Documentation Project you can chose one of two policies which dictates how the link will automatically update. Link policies can also be updated via the documentation editor after the link is created.

The default policy is latest where the link will automatically refer to the latest API version in the API project. This does not include pre-release versions such as 1.0.0-rc.1.

If you select the pinned policy then the API link will never automatically update and you will be responsible for manually updating the link when necessary. This policy can be useful if you want more explicit control over how the link updates or if you wish to include API references for a pre-release version.

Sideko displays all the information your API consumers will need to get started with your API. This section will detail which specific field(s) are used in the documentation generation.

An operation's operationId (converted to title case), summary, and description are used to populate the reference's label, title and long-form description respectively.

OpenAPI uses JSON schema to describe an APIs inputs and outputs. Sideko generates an interactive and collapsible JSON schema viewer for the request parameters, body, and response body. For example:

Sideko will generate example code snippets for calling each endpoint. We suggest specifying named examples in the requestBody.content.{contentType}.examples field. For each named example, Sideko will generate a code snippet in each supported language. If there are no examples listed in the suggested field, Sideko will generate examples from the example values in the JSON schema, falling back on some default example values for each type.

For more information on specifying named request body examples please refer to the OpenAPI documentation.

Sideko will also display example response data for each response code/content type listed in OpenAPI. We suggest specifying named examples in the responses.{responseCode}.content.{contentType}.examples field. If there are no examples listed in the suggested field, Sideko will generate examples from the example values in the JSON schema, falling back on some default example values for each type.

For more information on specifying named response examples please refer to the OpenAPI documentation.

The output of Sideko's generated API References (used in Documentation Projects) can be customized using a variety of extension fields (x-sideko-*) embedded directly into OpenAPI.

The global Sideko documentation config resides at the root of the OpenAPI specification under x-sideko.docs.

x-sideko:
  sdks:
    hiddenOperationIds:
      # Generated API Reference will only include the listDeployments method
      - createDeployment
      - updateDeployment
paths:
  /projects/{id}/deployments:
    get:
      operationId: listDeployments
      ...
    post:
      operationId: createDeployment
      ...
    patch:
      operationId: updateDeployment
      ...

Using the following configuration, you can expect getItemV1 getItemV2 to be condensed into one API Reference page.

x-sideko:
  docs:
    versionedOperations:
      # Labels must be unique
      - label: Create Item
        paths:
          # Path labels must be unique within a versioned operation
          - label: v2
            operationId: createItemV2
          - label: v1 (deprecated)
            operationId: createItemV1
 
paths:
  /v1/item:
    get:
      operationId: List Items
      summary: Retrieves Item
      ...
    post:
      operationId: createItemV1
      summary: Create Item (deprecated)
      ...
  /v2/item:
    post:
      operationId: createItemV2
      summary: Create Item
      ...