Add API Documentation¶
API documentation helps API subscribers to understand the functionality of the API and API publishers to market their APIs better and sustain competition. Using the API Publisher, you can add different types of documentation from various sources. All documents created in the API Publisher have unique URLs to help improve SEO support.
The documentation types supported in the API Publisher are as follows:
- In-line: Hosts documentation (How-tos, Samples, SDK, forums etc.) in WSO2 API Publisher itself and allows it to be edited directly via the UI.
- URL: Links of public or support forums or file references (URLs) of an external configuration management system.
- File: Allows to upload the documentation directly to the server.
- Markdown: Allows to add markdown (
.md
) docs via a Markdown editor.
Follow the instructions below to add documentation to an API:
-
Sign in to the WSO2 API Publisher.
https://<hostname>:9443/publisher
-
Click on the API (e.g.,
PizzaShackAPI 1.0.0
) for which you want to add the documentation. -
Add the specific documentation.
Follow the steps below for each type.
- Add in-line documentation
- Add documentation using a URL
- Add documentation using a file
- Add Markdown documentation
Add in-line documentation¶
-
Click Documents and click Add New Document.
-
Enter the following details to create an in-line document.
Name PizzaShack Summary This is the official documentation for the PizzaShack API Type How To Source In-line -
Click Add Document.
-
Click Add Content to open an embedded editor.
Note
You can edit the content later by clicking Edit Content. It will open up the embedded editor to proceed.
-
Edit the document content in-line using the embedded editor and click Update Content.
The API's Documents tab opens.
Add documentation using a URL¶
You can use either Public Forum, Support Forum or Other types to add documentation using a URL.
Add a document using a URL based on a Public Forum/Support Forum¶
-
Click Add New Document to add another documentation type.
-
Enter the following information to create another doc using a URL of a Public or Support forum.
Name APIForum Summary Forum to discuss about APIs
Type Public Forum/Support Forum Source URL
http://www.dummyforum.com
Add an other type URL based document¶
You can use this if you want to add a document using the Other type that points to a link that has a file reference of an external source.
-
Enter the following information to create another doc using a URL.
Name PizzaShackWiki Summary Sample PizzaShack API
Type Other Other Document Type Other (Provide a type as required) Source URL
http://www.dummy.com/PizzaShackAPIDoc.pdf -
Click Add Document.
The API's Documents tab opens.
Add documentation using a file¶
-
Click Add New Document to add yet another document using a file.
-
Enter the following information.
Name APIManagerSamples Summary API Manager Samples Type Samples & SDK Source You can provide any of the allowed file formats. Use the sample PDF here.
Note
The API Manager allows to configure the types of files that can be uploaded as documentation using below configuration. By default, the allowed file types include pdf, txt, doc, docx, xls, xlsx, odt, ods, json, yaml, and md.
- Click Add Document.
Add Markdown documentation¶
-
Click Documents and click Add New Document.
-
Enter the following details to create Markdown documentation and click Add Document.
Name PizzaShackAPIDocumentation Summary This is the official documentation for the PizzaShack API Type How To Source Markdown -
Click Add Content to open an embedded editor.
-
Edit the document content using the embedded markdown editor and click Update Content.
The API's Documents tab opens.
You have now added four type of documents to the API: in-line, URL, file, and markdown.
-
Sign in to the WSO2 Developer Portal and click on the
PizzaShackAPI
version 1.0.0 API.https://<hostname>:9443/devportal
-
Click Documents.
The documents that you added, which are listed by type, appears.
-
Use the dropdown and select the document that you want to view.
As a subscriber, you can read the documentation and learn about the API.
You have created documentation using the API Publisher and viewed the documentation as a subscriber in the Developer Portal.
Control API Document Visibility in Developer Portal¶
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).
Note
This feature has been disabled in the default setup.
Enabling document visibility in Developer Portal¶
To enable other visibility levels to the documentation, go to the <API-M_HOME>/repository/conf/deployment.toml
, add the following configuration.
- 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.
- Owner Only: Visible to all registered users in the API's tenant domain.
- Private: Visible only to the users who have permission to log in to the API Publisher web interface and create and/or publish APIs to the Developer Portal in the same tenant domain.
Control API document visibility using the API Publisher¶
-
Sign in to the API Publisher as an API creator using the following URL:
https://<localhost>:9443/publisher
-
Create a new API or edit an existing API.
-
In the Documents tab, Click Add New Document, to see a new drop-down list added to select visibility from.
-
Add the Document.