Generating REST API docs using swagger yamls for WSO2 Open Banking

This blog is very specific and will be useful only when you try to do what this title says.

Prerequisites

• Make sure you have access to the Support- OB GitHub repository. This is a private repo, so in case if you don’t have access immediately request access. Meanwhile, you can tick off the following items
• Install Oracle JDK 1.8 or later
• Install Maven 3.0.5 or later
• Now you need the swagger yaml files of the REST APIs. Find out the GitHub links and locate the files inside the repo itself

Setting up the GIT Repo & Swagger files

• Fork and clone the Support-OB repo, to a directory you want

git clone <forked url>

• Add the Support-OB repo GitHub repo as the ‘upstream’ of your clone. To do this, go to the cloned directory and execute the commands below

cd financial-open-banking-1/
git remote add upstream <Support-OB-repo_URL>

• Verify whether you set the upstream properly

The origin is the forked repo URL and the upstream is the Support OB repo URL

git remote -v
origin git@github.com:<Forked-OB-repo_URL> (fetch)
origin git@github.com:<Forked-OB-repo_URL>(push)
upstream git@github.com:<Support-OB-repo_URL>(fetch)
upstream git@github.com:<Support-OB-repo_URL> (push)

• Now you need to fetch. This is syncing your forked repo with the latest upstream code base. You need to fetch the branches and their respective commits from the upstream repository

git fetch upstream

• Let’s create a new local branch in the forked repo named apidoc-130 from the upstream (support-1.3.0 branch)

Which means you will have the same code base as Support-OB 1.3.0 branch, locally.

git checkout -b apidoc-130 upstream/support-1.3.0

• Make sure you checked out the correct version. You can do this by using the product root pom(outer most pom file). Open the pom file and verify the branch using the <version> tag.

(Assuming you are in product repo home, in which you have the root pom)

cat pom.xml

the output would be a file starting like this

<groupId>com.wso2.finance</groupId>
<artifactId>open-banking</artifactId>
<packaging>pom</packaging>
<version>1.3.0</version>
....

Modify the swagger files you want to convert

So basically this is how it should be reviewed:

• Review grammar
• Add descriptions for the commands and attributes
• Add sample CURL commands and responses
• Make sure the usernames given in sample CURL commands are gender-neutral etc.
• Always check with the https://editor.swagger.io/ when you are reviewing the swagger yamls.

From your fork, create pull requests for each file you edit and get them merged. Make sure your PRs are less complicated and easy to digest

Generating REST API docs

• Download the “swagger doc generator” tool onto your machine. This tool is customized to generate REST API docs for WSO2 swagger files.

(Fork the repo and clone it. Check out the below branch which is customized with the OB template)

isharailanga/swaggerdocumentgenerator

• If there are any custom templates to be used, add them to the swaggerdocumentgenerator/templates folder.

You can only generate HTML swagger docs for one YAML file at a time. This means that even if there are several YAML files inside the swagger-yaml folder, this tool will result in only a single set of HTML content related to the yaml file mentioned in the swaggerdocumentgenerator/pom.xml file.

Follow the steps below for each yaml file to get the respective html content generated.

• Copy the yaml file and paste it in the swaggerdocumentgenerator/swagger-yaml folder.
• Open the swaggerdocumentgenerator/pom.xml file using a text editor and update the <swagger.yaml.file.name> property (roughly line 125) with the name of your yaml file.

<properties>
<swagger.yaml.file.name>abc-130.yaml</swagger.yaml.file.name>
</properties>

• Open a terminal from the location where you have the swaggerdocumentgenerator/pom.xml and run the command below

mvn clean install post-site

• If the swagger docs were generated successfully, a message displaying “BUILD SUCCESS” will be displayed on the terminal.
• You will find a doc.zip file inside the swaggerdocumentgenerator/doc folder.

(Assuming that you are using Ubuntu and XAMPP)

• Start the XAMPP server.

sudo /opt/lampp/lampp start

• Copy the zip files to the /opt/lampp/htdocs and host them. There you can view the REST API docs and fix any content issues.

or

• Extract the .zip file and use Firefox-Web browser to edit the HTML pages as required.

Once reviewed and verified:

• Host the zip files in appropriate URLs.

abc-130 swagger : https://docs.wso2.com/<OB-doc-space>/apidocs/abc-130/

• Link to this REST API doc URL from the relevant places in the product documentation space.