Andrew Owen | Writer

#VScode #ReDoc #JSON #DevPortal

In this three part series, I’ll outline how to create a fully featured dev portal for your Swagger or OpenAPI 3.0 content without spending a dime. You can read part one here and part three here.

Part II: Tools

When I wrote the original version of this guide, I was an API writer creating docs for an event-driven e-commerce solution. Event driven architecture (EDA) is something I’ll talk more about in a future article. Development was done primarily in .NET and API docs were generated using Swashbuckle (also a good topic for a future article). This is known as the code first or bottom up approach. The more your code grows, the harder it is to maintain consistent APIs with this approach.

In my view, you should create your API specification and code against that. But for the purposes of this guide, I’ll assume that you don’t have any say in that, and you just have to get the API docs into the hands of developers. You may not even have an API schema, in which case you should create one in Postman, based on whatever API documentation you have available to you.

IDE

Visual Studio Code

If you’re using windows and writing API docs directly in the code, you may be using Visual Studio. If you’re not using Windows, then the next best thing is Visual Studio Code.

Before you set up your dev environment, ensure you have installed the CLI tools.

Set up a .NET dev environment

Download and install the Visual Studio Code editor.
Download and install the .NET Core SDK.
Create a folder called development where you want to store your local repositories.
In BitBucket Server, go to the repository you want to work with and click the clone icon from the left toolbar.
Copy the HTTP address.
In the PowerShell / Terminal, navigate to the development folder.
Enter git clone and paste the HTTP address to complete the line.

Build the OpenAPI 2.0 (Swagger) JSON file

This assumes you have a working .NET dev environment and have correctly configured Swashbuckle:

In PowerShell / Terminal, navigate to the src folder in your local repository.
Enter dotnet build.
Navigate to the folder where the DLL was built and enter dotnet run.
In Chrome, navigate to the URL shown in the build output. Example: http://127.0.0.1:5000.
Click the /swagger/v1/swagger.json link to download the JSON file.

Plug-ins

Some recommended plug-ins for Visual Studio Code include:

• Better TOML by bungcip

• C/C++ by Microsoft

• C# by Microsoft

• Code Spell Checker by Street Side Software

• GitLens by Eric Amodio

• Markdown Preview Enhanced by Yiyi Wang

• Prettier - Code formatter by Esben Petersen

Preview API doc changes

Requirements

• You can create tasks to automate processes in Visual Studio Code.

• Each repository requires its own set of tasks.

• You must add .vscode/ to the .gitignore file to any repository you intend to use tasks with.

• Separate scripts are required for macOS and Windows.

Convert Swagger JSON to ReDoc HTML

Enter: redoc-cli bundle <filename>.json.

Running scripts

• After you have configured the scripts for a given repository, you can run them from Visual Studio Code.

• Press command+shift+B (macOS) or ctrl+shift+B (Windows) to run the build task.

• The ReDoc HTML file is opened in Chrome.

• If the server takes a long time to start, the ReDoc task will fail. After the server has started, run the ReDoc task from the Terminal menu.

Example Visual Studio Code tasks JSON file

This file should be placed inside the .vscode folder in the Git repository and .vscode added to the .gitignore file.

tasks.json

    {
      "version": "2.0.0",
      "tasks": [
        {
          "label": "build",
          "command": "dotnet",
          "type": "process",
          "args": [
            "build",
            "${workspaceFolder}/src/Dev.Example.Com.Myproject/Devg.Example.Com.Myproject.csproj"
            ],
            "problemMatcher": "$msCompile"
          },
          {
            "label": "Swagger",
            "type": "shell",
            "command": ".vscode/swagger.sh",
            "windows": {
            "command": ".vscode\\swagger.cmd"
          },
          "presentation": {
            "reveal": "always",
            "panel": "new"
          }
        },
        {
          "label": "ReDoc",
          "type": "shell",
          "command": ".vscode/redoc.sh",
          "windows": {
            "command": ".vscode\\redoc.cmd"
          },
          "presentation": {
            "reveal": "always",
            "panel": "new"
          },
         "problemMatcher": []
       },
       {
          "label": "Build API Docs",
          "dependsOn": ["Swagger
  - ReDoc"],
          "group": {
            "kind": "build",
            "isDefault": true
          },
        }
      ]
    }

Example scripts (macOS)

redoc.sh

    cd ~/
    rm redoc.jsonrm redoc-static.html
    
    # wait for server to start
    echo waiting for service to start
    sleep 10
    
    curl -o redoc.json http://localhost:62512/swagger/v1/swagger.json
    redoc-cli bundle redoc.json
    open -a "Google Chrome" redoc-static.html

swagger.sh

    export CONSUL=[http://consul.dev.example.com](http://consul.dev.example.com "http://consul.dev.example.com")
    cd src
    dotnet build --source [http://dev.example.com/myproject/](http://dev.example.com/myproject/ "http://dev.example.com/myproject/")
    cd Dev.Example.Com.Myproject
    dotnet run --urls=http://localhost:62512

Example scripts (Windows)

redoc.cmd

    cd ~/
    del redoc.json
    del redoc-static.html
    
    # wait for server to start
    echo waiting for service to start
    sleep 10
    
    curl -o redoc.json

swagger.cmd

    set CONSUL=http://consul.dev.example.com
    cd src
    dotnet build --source http://dev.example.com/myproject/
    cd Dev.Example.Com.Myproject
    dotnet run --urls=http://localhost:62512

Creating a developer portal with no budget (part 2/3)