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.
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.
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.
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.
Add an external source if you'd like to host your API documentation outside of the API manager.
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
, andOPTIONS
(required). -
In Access-Control-Allow-Headers, add:
access-control-allow-origin
,x-celigo-api-key
, andcontent-type
. -
Toggle the Access-Control-Allow-Credentials button ON.
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.
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.
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.
To edit existing documentation:
-
Navigate to your API → Documentation.
-
Edit your specification directly in the editor or upload a new file.
-
Click Save.
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.
Comments
Article is closed for comments.