You can add different types of documents to an API. Proper documentation helps API publishers to market their APIs better and sustain competition. Follow the steps below to add documentation to an API using the API Publisher Web interface.
- Log in to WSO2 API Publisher with a user who has been assigned the creator role. For information on users and roles, see Managing Users and Roles.
- The currently available APIs appear on the All APIs window. Select the API to which you want to add documentation to.
- Select the Docs tab of the API and click the Add New Document link.
Documentation can be provided inline, via a URL or as a file. - In-line: Documentation hosted in the API Manager itself. For inline documentation, you can edit the contents directly from the API publisher interface. You get several documents types:
- Swagger documents
- How To
- Samples and SDK
- Public forum / Support forum (external link only)
- API message formats
- Other
- URL: If you already have comprehensive documentation managed by an external configuration management system, you can simply link to those file references (URLs) through the API Manager rather than importing them to the server.
- In-line: Documentation hosted in the API Manager itself. For inline documentation, you can edit the contents directly from the API publisher interface. You get several documents types:
- Click the Add Document button to complete.
- The added document shows on the same window. Click the Edit Content link associated with it.
- The embedded editor opens allowing you to edit the document content.
All documents have unique URLs to help improve SEO support. After editing the API, publish it for it to be available to external parties through the API Store.
By default, any document associated with an API has the same visibility level of the API. That is, if the API is public, its documentation is also visible to all users (registered and anonymous). To enable other visibility levels to the documentation, go to
<AM_HOME>/repository/conf/api-manager.xml file, uncomment and set the following element to true: <APIPublisher> .... <EnableAPIDocVisibilityLevels>true</EnableAPIDocVisibilityLevels></APIPublisher> |
Then, log in to the API Publisher, go to the Doc tab and click Add new Document to see a new drop-down list added to select visibility from. The settings are as follows:
- Same as API visibility: Visible to the same user roles who can see the API. For example, if the API's visibility is public, its documentation is visible to all users.
- V isible to my domain: Visible to all registered users in the API's tenant d omain.
- Private: Visible only to the API creator's role.
Next, see Adding Documentation Using Swagger.