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 in the API's Documentation section (v4) or at APIs → <Your API> → Documentation (v2). Learn more about YAML files and working with YAML.

Important: You must review and publish your API documentation before it's available for consumers.

Note: Several paths in this article depend on your API definition version. v4 APIs use the current console layout; v2 APIs use the legacy layout. Learn more about API definitions.

Navigate your documentation

After pushing your resource to the APIM console using the Celigo platform, open your API's Documentation section 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.

Documentation for v4 APIs

The Documentation section has three tabs: Main Pages, Documentation Pages, and Metadata.

The Documentation Pages tab lists your pages in a folder tree starting at Home, including the auto-generated OpenAPISpec.yaml. Each page shows its Status (Published or Unpublished) and Visibility, with actions to edit, publish or unpublish, reorder, and delete. Select Open API in Developer Portal to preview how your documentation appears to consumers.

The Metadata tab lets you set API metadata that you can easily access through Markdown templating. In most cases, an email support key is added automatically.

API_documentation_pages.jpg

Open a page to configure it from three tabs — Configure Page, Configure OpenAPI Viewer, and Content — and use Toggle preview to render the OpenAPI viewer. Select Save to save your changes, or Save and publish to save and publish them together.

api_documentation_content.jpg

Documentation for v2 APIs

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.

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 selecting 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.

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.

API_documentation_configure.jpg

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.

There are several guidelines you should follow when configuring CORS:

  • Enable and configure CORS at the API Level, not at the environment level.
  • Instead of using a wildcard (*) for Access-Control-Allow-Origin, explicitly list the domains that are permitted to access the API.
  • Define only the necessary HTTP methods (ex. GET, POST, PUT, DELETE) and headers that your API expects.
  • Understand how preflight requests (OPTIONS requests) work and configure Access-Control-Allow-Methods and Access-Control-Allow-Headers to respond appropriately to these requests, ensuring smooth communication for complex cross-origin interactions.
  • Strictly enforce security measures, including authentication and authorization, even if CORS is configured.
  • Periodically review your CORS policies and update them as your application's architecture or security requirements evolve. Remove any outdated or overly permissive rules.
  • After configuring CORS, thoroughly test your API from various origins to ensure that legitimate requests are allowed and unauthorized requests are blocked as intended.

To enable CORS:

  1. Navigate to Entrypoints → CORS (v4) or Proxy → CORS (v2), and turn on Enable CORS.

    api_entrypoint_cors.jpg
  2. In Allow-Origin, add the console and portal origins: https.*.console.apim.integrator.io and https.*.portal.apim.integrator.io. Regular expressions are supported.
  3. In Access-Control-Allow-Methods, add GET, DELETE, PATCH, POST, PUT, and OPTIONS (required).
  4. In Allow-Headers, add access-control-allow-origin, x-celigo-api-key, content-type, and authorization.
  5. Turn on Access-Control-Allow-Credentials.
  6. Optionally, set a Max Age for preflight responses and turn on Run policies for preflight requests.

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.

For v4 APIs, open your API spec in the Documentation section and select Configure OpenAPI Viewer to enable Try-it.

api_documentation_pages_config_viewer.jpg

For v2 APIs, 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.

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 for a v4 API:

  1. Open your API and select Documentation → Documentation Pages.
  2. Select Add new page or Add new folder.
  3. Choose the page format and add your content, or upload a file directly from your desktop.

To add documentation for a v2 API:

  1. Navigate to API → Documentation.
  2. Select 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.

Edit documentation

To edit existing documentation for a v4 API:

  1. Open your API and select Documentation → Documentation Pages.
  2. Select the page and edit it in the Content tab, or upload a new file.
  3. Select Save, or Save and publish to publish your changes immediately.

To edit existing documentation for a v2 API:

  1. Navigate to API → Documentation.
  2. Edit your specification directly in the editor or upload a new file.
  3. Select Save.

Configure authentication (optional)

You can configure bearer token authentication for your API documentation in the OpenAPI viewer (v4) or the Page section (v2).

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

    api_documentation_content.jpg
  2. Select Authorize.

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

    api_documentation_content_auth.jpg

  4. Select 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

Publish your documentation to make it available in the Developer Portal for consumers:

  • In the page list, select the publish (cloud) icon for the page. The same icon also unpublishes your documentation.
  • In the page editor (v4), select Save and publish.

Related articles