A Remedy to Manage API Documentation using WSO2 API Controller

Wasura Wattearachchi

Follow

Apr 30 · 11 min read

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 sourceTypeas INLINE 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 named Inline Document , which belongs to the type HOWTO 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 sourceTypeas MARKDOWN 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 named Markdown Document , which belongs to the type SAMPLES (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 sourceTypeas FILE 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 named File Document , which belongs to the type HOWTO along with a summary. The file path specified here is myfile.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 sourceTypeas URL 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 named URL Document , which belongs to the type PUBLIC_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 as OTHER in the metadata entry and you can specify the custom type in the field otherTypeName . 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 named Other Type , which belongs to the type OTHER along with a summary. The custom type of the document is specified as Custom Type using the field otherTypeName.
• 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!

References