A Remedy to Manage API Documentation using WSO2 API Controller
Pop Quiz! Are you looking for guidelines or a way to manage API documentation using WSO2 API Controller (apictl)?

Documenting your APIs is a part of the API Management process. As the WSO2 API Manager (WSO2 API-M) official documentation says,
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.
Of course, you may already know how to add, delete or edit API documentation using the Publisher Portal of WSO2 API Manager (WSO2 API-M). But most of you might be wondering how to achieve this using the WSO2 API Controller (apictl), right? I have seen people asking questions in Stack Overflow and Slack regarding this. This is the perfect place for YOU guys!
If you have read my articles before or if you are a fan of WSO2 API-M, you may already know what apictl means. apictl is a command-line tool for managing API Manager environments, listing APIs, API products and applications, creating API projects, importing and exporting APIs, API products and applications, generating tokens for APIs and API products for testing purposes, etc. Refer to the below link to learn more.
In this article, I will show you how to manage (import/export) API documentation using WSO2 API-M 3.2.0 and apictl 3.2.x. But note that,
The same way can be used for any predecessor WSO2 API-M version (<3.2.0) and for any predecessor apictl version (<3.2.x). Don’t consider this as just a tutorial, this is something more… A remedy!
First Things First

Refer to the following prerequisites if you want to have a hands-on experience with what I am going to teach. Otherwise, you are free to ignore this.
Under the assumption that you have already installed Oracle Java SE Development Kit (JDK) version 11.\* or 1.8.\* and set the JAVA_HOME
environment variable (For more information on setting the JAVA_HOME
environment variable for different operating systems, see Setup and Install.) you need to satisfy the below requirements.
- Download the latest version of WSO2 API Manager (Here I have used WSO2 API Manager 3.2.0)
- Download and initialize API Controller 3.2.0 (apictl 3.2.x)
Different Documentation Sources and Types
There are four (4) documentation sources supported by WSO2 API-M: Inline, Markdown, File, and URL.
For each of these sources, you can select the type of the document whether it is a “How to” or a “Sample & SDK” or “Other”. If you select “Other” you can specify any custom type as you desire. Apart from these three (3) types, there are another two (2) forum types as “Public Forum” and “Support Forum”. But these two (2) types only allow to add documentation as URLs, not any other source type.
If you are confused with what I explained earlier, don’t worry… The below table contains a summary of the supported sources for each type of documentation which will make this idea more simpler for you.

When it comes to the sources and the types of documentation, the main focus should go to the sources. You can attach any document that belongs to any source category (which belongs to any type) to your API/API Product project and import it (using the apictl import command) so that the documents will get automatically added along with the API/API Product.
I will take you through five (5) steps that can be considered as a remedy to manage API documentation using apictl.
Step 1 — Create your API project or export an existing API/API Product Project from a WSO2 API-M instance
In this step, you can either create an API project from the scratch using apictl init command or you can export an existing API/API Product from a WSO2 API-M instance using the apictl export-api / apictl export api-product commands.
If you are familiar with apictl this step is simple for you. What do you think?

Do not worry! The main aim of this step is to equipped us with an API/API Product so that we can add documents to it later as we wish. For the demonstration purpose, I will execute the below command to create an API project from the scratch.
./apictl init Petstore --oas https://petstore.swagger.io/v2/swagger.json
The initialized API project will have the below structure.
Petstore
├── api_params.yaml
├── Docs
│ └── FileContents
├── Image
├── Interceptors
├── libs
├── Meta-information
│ ├── api.yaml
│ └── swagger.yaml
├── README.md
└── Sequences
├── fault-sequence
├── in-sequence
└── out-sequence
The directory that we should be focusing on when adding the documentation is the Docs directory.
Step 2— Add documentation to the Docs directory

Now it is the time to take the most important step in this remedy. When you are adding documents to an API/API Product Project, the first thing that you should do is to create a file named docs.yaml inside the Docs directory.
What is the docs.yaml file?
docs.yaml file is the file that contains the metadata of all the documents of your API/API Product. A sample docs.yaml file is shown below.
-
type: HOWTO
name: Inline Document
summary: This is a sample inline document
sourceType: INLINE
visibility: API_LEVEL
-
type: SAMPLES
name: Markdown Document
summary: This is a sample Markdown document
sourceType: MARKDOWN
visibility: API_LEVEL
-
type: PUBLIC_FORUM
name: URL Document
summary: This is a sample URL document
sourceType: URL
sourceUrl: https://apim.docs.wso2.com/en/3.2.0
visibility: API_LEVEL
-
type: HOWTO
name: File Document
summary: This is a sample file document
sourceType: FILE
filePath: myfile.pdf
visibility: API_LEVEL
-
type: OTHER
name: Other Type
summary: Sample for a custom type
sourceType: INLINE
otherTypeName: Custom Type
visibility: API_LEVEL
Don’t worry if you cannot understand the content inside this file. But, did you notice that this file has the details of the documents as an array (An array of five documents)? For now, just remember that,
docs.yaml stores the metadata of all the documents of an API/API Product in an array format.
Next, I will discuss how you can add documents belong to each source category.
Adding an INLINE document
- If you want to add an Inline document to your API/API Product, you need to specify the
sourceType
asINLINE
in the metadata entry inside the docs.yaml file. Refer to the below example.
-
type: HOWTO
name: Inline Document
summary: This is a sample inline document
sourceType: INLINE
visibility: API_LEVEL
- The above metadata entry specifies an
INLINE
document namedInline Document
, which belongs to the typeHOWTO
along with a summary. - Adding this metadata entry only is not enough if you want to add the inline documentation content as well. You need to create a folder named, InlineContents inside the Docs directory (if it currently does not exist).
- Inside that InlineContents directory create a file that has your document name. (According to the above example it should be “Inline Document”)
- Make sure that you do not give any extension to your file. (For example, the file should be just “Inline Document” not “Inline Document.txt” or with any other extension). I will add the below content to my “Inline Document” file for the demonstration.
<p><strong>My inline content</strong></p>
<p>This is a sample inline document</p>
- Now the structure of my Docs directory will look like below.
Docs
├── docs.yaml
└── InlineContents
└── Inline Document
Adding a MARKDOWN document
- This is similar to what we did in the previous section on Adding an INLINE document.
- If you want to add a Markdown document to your API/API Product, you need to specify the
sourceType
asMARKDOWN
in the metadata entry inside the docs.yaml file. Refer to the below example.
-
type: SAMPLES
name: Markdown Document
summary: This is a sample Markdown document
sourceType: MARKDOWN
visibility: API_LEVEL
- The above metadata entry specifies a
MARKDOWN
document namedMarkdown Document
, which belongs to the typeSAMPLES
(Samples & SDKs) along with a summary. - As we did in the previous section, to add the markdown content of the document, create a directory named InlineContents inside the Docs directory (if it currently not exists).
- Inside that InlineContents directory create a file that has your document name. (As per the above example it should be “Markdown Document”)
- Make sure that you do not give any extension to your file. (For example, the file should be just “Markdown Document” not “Markdown Document.txt” or with any other extension). I will add the below content to my “Markdown Document” file for the demonstration.
# My markdown ContentThis is a sample markdown document
- Now the structure of my Docs directory will look like below.
Docs
├── docs.yaml
└── InlineContents
├── Inline Document
└── Markdown Document
Adding a FILE
- If you want to add a FILE to your API/API Product, you need to specify the
sourceType
asFILE
in the metadata entry inside the docs.yaml file. Refer to the below example.
-
type: HOWTO
name: File Document
summary: This is a sample file document
sourceType: FILE
filePath: myfile.pdf
visibility: API_LEVEL
- The above metadata entry specifies a
FILE
namedFile Document
, which belongs to the typeHOWTO
along with a summary. The file path specified here ismyfile.pdf
which is the actual file name that you are going to add. - You need to create a directory named FileContents inside the Docs directory (if it currently not exists).
- Add your file (
myfile.pdf
according to the above example) to the FileContents directory. - Now the structure of my Docs directory will look like below.
Docs
├── docs.yaml
├── FileContents
│ └── myfile.pdf
└── InlineContents
├── Inline Document
└── Markdown Document
Adding a URL
- If you want to add a URL document to your API/API Product, you need to specify the
sourceType
asURL
in the metadata entry inside the docs.yaml file. Refer to the below example.
-
type: PUBLIC_FORUM
name: URL Document
summary: This is a sample URL document
sourceType: URL
sourceUrl: https://apim.docs.wso2.com/en/3.2.0
visibility: API_LEVEL
- The above metadata entry specifies a
URL
document namedURL Document
, which belongs to the typePUBLIC_FORUM
along with a summary. - Make sure to specify the
sourceUrl
that will contain your actual URL.
Adding a custom type document
- When adding a document belong to any of the source types (Inline, Markdown, File or URL), you can add a document with a custom type if you wish.
- To add that kind of a document, you need to specify the
type
asOTHER
in the metadata entry and you can specify the custom type in the fieldotherTypeName
. Below is an example of that.
-
type: OTHER
name: Other Type
summary: Sample for a custom type
sourceType: INLINE
otherTypeName: Custom Type
- The above metadata entry specifies an
INLINE
document namedOther Type
, which belongs to the typeOTHER
along with a summary. The custom type of the document is specified asCustom Type
using the fieldotherTypeName
. - Since this is an Inline document, make sure to add the contents to InlineContents directory as discussed in the section Adding an INLINE document.
- Now the structure of my Docs directory will look like below.
Docs
├── docs.yaml
├── FileContents
│ └── myfile.pdf
└── InlineContents
├── Inline Document
├── Markdown Document
└── Other Type
Now we have an API project along with some documents.
Step 3— Import an API/API Product with the Documentation
As the next step, you can import this API/API Product project to a WSO2 API-M instance along with the documentation. Let’s execute the below command to import the API. (You can find my Petstore API project here which I am using here for the demonstration. Refer to it if you need further understanding)
apictl init Petstore — oas https://petstore.swagger.io/v2/swagger.json
Now go to the Publisher Portal of the WSO2 API-M instance and check the documentation tab of your API. You can see the documents are added as you wished.


Now you have successfully imported an API along with the documentation using apictl. Amazing isn’t it?
Step 4— Update an API/API Product Documentation
Of course, adding the documentation to an API is not enough. You should have the ability to maintain those by updating. You can do it in a snap of your fingers.
- If you wish to update the metadata of your documents, you need to change the docs.yaml file with the updated metadata.
- If you want to update the documentation content inside the directories InlineContents and FileContents, you just have to edit the existing files inside those directories or add new files or remove files as you wish.
In either case, you just need to do as you wish. After that, you need to import the API with the --update
flag. (For API Products you can use --update-api-product
flag. See A Gift to DevOps to Migrate API Products for more information.)
Step 5— Remove an API/API Product Documentation
If you want to remove a document, you just need to remove the metadata entry (of the corresponding document that you wish to delete) from the docs.yaml file and import the API again with the --update
flag. (For API Products you can use --update-api-product
flag. See A Gift to DevOps to Migrate API Products for more information.)
- For the demonstration, I will remove the below record from the docs.yaml file.
-
type: HOWTO
name: Inline Document
summary: This is a sample inline document
sourceType: INLINE
visibility: API_LEVEL
- Now, I will re-import the API with the update flag using the below command.
./apictl import-api -f Petstore -e production --update
- Go to the Publisher Portal of the WSO2 API-M instance and check the documentation tab of your API. You can see that the “Inline Document” is not there.


Now you have learned how to successfully remove a document from your API using the apictl.
Let’s windup
In this article I wanted you to clarify the doubts that most of you were having when managing documentation using the WSO2 API Controller (apictl). Some of you were wondering what are the correct guidelines to be followed when adding documents to an API using apictl.

In this article, I showed you how to add different sources of documents such as Inline, Markdown, File and URLs in a snap of your fingers attached to an API using the apictl.
Here I used WSO2 API-M 3.2.0 and apictl 3.2.x. But you can try this remedy with older WSO2 API-M and apictl versions as well. Further, you can try the same remedy for API Products too. (But note that, API Products have been introduced from WSO2 API-M 3.2.0 onwards. Refer here for more details)
Thanks and Goodbye until the next time…
Stay safe everyone!