Configure and publish APIM documentation

Kathyana Queeman

Updated April 30, 2024 17:20

In most cases, your API documentation is automatically generated and uploaded by Celigo’s integrator.io 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 a MyAPI import or export since they're 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 own 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.

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

Page

This is your 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

This is where you can add a translation for your documentation to another language.

Configuration

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

External source

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

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:

Navigate to API → CORS and toggle the Enable CORS button ON.
In Access-Control-Allow-Origin, add: https.*.portal.apim.<environment>.integrator.io.
In Access-Control-Allow-Methods, add: GET, DELETE, PATCH, POST, PUT, and OPTIONS (required).
In Access-Control-Allow-Headers, add: access-control-allow-origin, x-celigo-api-key, and content-type.
Toggle the Access-Control-Allow-Credentials button ON.

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.

Add, edit, or update documentation

You can choose to add, edit, or update existing documentation through your APIM console. As previously mentioned, in most cases, integrator.io will automatically generate an OpenAPI specification for you. The main exception is MyAPI exports or imports, since they're script-based.

Add documentation

To add documentation:

Navigate to your API → Documentation.
Click Add new page or Add new folder .
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:

Navigate to your API → Documentation.
Edit your specification directly in the editor or upload a new file.
Click Save.

Configure authentication (optional)

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

Visually confirm the Server URL. If your API was created through integrator.io, this will be automatically filled in.
Click Authorize.
Add your bearer authentication token value or other method of validation.
Click Authorize and close your authorization.

Note

You can also Log out to remove your authorization from the document after you finish working with it.
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.