Specify API routes and object and publish API documentation

To manage this work, I created a new project in the MyITS suite: myits-swagger

Swagger in the a suite of tool well designed to build dynamically a RESTful API specification. We will use here 2 main tools of the suite :

  • Swagger-editor to edit the API specification and visualize in live the update
  • Swagger-ui to display the API specification as a Web page

Swagger in docker

Swagger editor

To manage Swagger editor, I decide to use a swagger docker image. It is an option as you can use the online editor, it works well.

Here is the docker-compose.yml

services:
# interface to swagger editor
  swagger-editor:
    image: swaggerapi/swagger-editor
    restart: always
# Swagger editor will be available on http://localhost:8002
    ports:
      - 8002:8080
    container_name: myits-swagger-editor

Using Swagger editor in docker doesn’t provide extra feature as you still need to import and import your JSON configuration file to update it. There isn’t any option to defined default json file to load when it is started. It just allow you to run it locally.

Swagger UI

To manage Swagger UI, I create a Dockerfile. It uses swagger-ui official docker image as base and copy the api.json (our specification) in the docker image where it can be directly accessible via nginx public files.

FROM swaggerapi/swagger-ui

RUN mkdir /usr/share/nginx/html/api-url
COPY api.json /usr/share/nginx/html/api-url

CMD ["sh", "/usr/share/nginx/docker-run.sh"]

Then, in the docker-compose file, we use this Dockerfile to build our image and launch it. As default path API_URL, we set the URL of the api.json serve by itself.

  swagger-ui:
    build: 
      context: ./swagger-files
      dockerfile: Dockerfile.swagger-ui
    restart: always
# Swagger UI will be available on http://localhost:8003
    ports:
      - 8003:8080
    environment:
        API_URL: http://localhost:8003/api-url/api.json
    container_name: myits-swagger-ui

Swagger syntax & display: why it’s cool

Swagger editor provide on the left of the screen an editor for the API config in YAML, which is more user friendly than JSON, and generate on the right of the screen the specification as a webpage. As main advantage of Swagger technology:

  • All links between API result and object are automatically generated.
  • API response can be exhaustively describe
  • Error type are describe
  • A complet header is displayed included Base URL, Licence, Author, Description…

This is really useful to manage and generate API documentation

What can be better or I didn’t find yet :

  • How to manage it is some option to get multi pages Swagger UI
  • Overdefined thème

To continu with swagger

It is possible to auto-generate an API server or client using different language. I don’t use this kind of feature because it seems a good option at the begining but it never generate the ultimate solution, at least the solution you expect with plugin and library you need and quickly you start de rewrite all your API.

However, a lot of plugin exist to manage some feature using the specification file such as plugin to check the request validity ​(EX: swagger-express-validator).

Here is the my Swagger specification : api.json

And you’ll be able to consult API documentation web page here

Now, we have a good specification, we know what the API should do so let’s code this API.