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
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.
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.