Articles in this section

Configure and publish APIM documentation

Kathyana Queeman
Updated

In most cases, your API documentation is automatically generated and uploaded by the Celigo platform using OpenAPI specs. The YAML file is available in your APIM console under APIs → [Your API] → Documentation. Learn more about YAML files and working with YAML.

Important

You must review and publish your API documentation before it’s available for consumers.

Navigate your documentation

After pushing your resource to the APIM console using the Celigo platform, you can navigate to your API → Documentation to see your existing specification.

Note

Your OpenAPI specs will be uploaded automatically, with only a few exceptions. The biggest exception is if you've pushed JavaScript API(s) imports or exports, which are script-based.

If available, your specification will be titled OpenAPISpec.yaml. The landing page has two tabs. The first, Pages, shows you all your available documentation, including an Aside folder where you can add your private documentation. The second, Metadata, allows you to set metadata information on the API that can be easily accessed through Markdown templating. In most cases, an email support key is added automatically.

Docs_landing_page.png

Your Documentation section landing page allows you to manage various aspects of your specification. Most importantly, you can publish your documentation using the Cloud button.

Publish_API_docs_highlighted.png

After clicking on your API spec, you'll see several tabs allowing you to configure your documentation further.

Page

This is the landing page for your specific API document. Here, you can see your current documentation and add bearer token authentication to your documents, so users will have to use their token to view the documentation.

OAS.png

Translation

You can add a translation for your documentation to another language.

Configuration

Use this section to configure the main settings for your documentation. Here, you can enable Try-it mode and allow users to filter content, among other things.

Docs_Try_it_config.png

External source

Add an external source if you'd like to host your API documentation outside of the APIM console.

Access control

This allows you to specify a more granular level of access, including adding groups or roles.

Configure CORS (required for Try-it mode)

CORS is a mechanism that allows restricted resources (e.g., fonts) on a web page to be requested from another domain outside the domain from which the first resource was served.

You must enable CORS to use the Try-it feature, which allows your API consumers to try your API before subscribing to it. If you don’t want people to try your API beforehand, you don’t need to enable CORS. To enable CORS:

  1. Navigate to API → CORS and toggle the Enable CORS button ON.

  2. In Access-Control-Allow-Origin, add: https.*.portal.apim.<environment>.integrator.io.

  3. In Access-Control-Allow-Methods, add: GET, DELETE, PATCH, POST, PUT, and OPTIONS (required).

  4. In Access-Control-Allow-Headers, add: access-control-allow-origin, x-celigo-api-key, and content-type.

  5. Toggle the Access-Control-Allow-Credentials button ON.

Enable_CORS.png

Enable the Try-it feature (optional)

The Try-it feature allows API consumers to try your API without subscribing. CORS must be enabled to use this feature. Navigate to your API → Documentation → Configuration to enable Try-it. We recommend enabling the Try-it feature for anonymous users and showing the URL so users can download the documentation.

Docs_Try_it_config.png

Add, edit, or update documentation

Through your APIM console, you can choose to add, edit, or update existing documentation. As previously mentioned, the Celigo platform will automatically generate an OpenAPI specification for you in most cases. The main exception is JavaScript API(s) exports or imports, which are script-based.

Add documentation

To add documentation:

  1. Navigate to your API → Documentation.

  2. Click Add new page or Add new folder .

  3. Use ASCIIDOCS, ASYNCAPI, SWAGGER, MARKDOWN, or upload a YAML file directly from your desktop. You can also edit the YAML file directly on the Documentation page.

Docs_create_new.png

Edit documentation

To edit existing documentation:

  1. Navigate to your API → Documentation.

  2. Edit your specification directly in the editor or upload a new file.

  3. Click Save.

Docs_highlighted_upload_file.png

Configure authentication (optional)

You can configure bearer token authentication for your API documentation in the Page section.

  1. Visually confirm the Server URL. If your API was created through the Celigo platform, this will be automatically filled in.

    Docs_authorize_use.png

  2. Click Authorize.

  3. Add your bearer authentication token value or use another method of validation.

    Docs_Auth_API_Key.png

  4. Click Authorize and close your authorization.

    Note

    After working with it, you can also Log out to remove your authorization from the document.

  5. Save your changes and Close.

Publish your documentation

Click the cloud to publish your documentation and make it available in the Developer portal for consumers. The same button can also be used to unpublish your documentation.

Publish_API_docs_highlighted.png