In the previous section, we build the endpoint /apidocs that produces the swagger file, and this week we will integrate it into the Swagger UI. If you didn’t read the previous parts of the course, you can check the content list from the overview page.
Create GET swagger endpoint
In addition to /apidocs endpoint, we will create /swagger endpoint that gets the JSON file from /apidocs and shows with Swagger UI to visualize and interact with the API’s resources. (We don’t use api/v1 namespace with those endpoints since documentation pages might cover different versions of the API in the future.)
Let’s create the swagger_controller.rb file inside of the controllers folder and place the index action that renders swagger layout without any view file.
Then we can create the layout file for the index action we defined.
I got the HTML template from petstore.swagger.io address but changed the asset URLs to use jsdelivr.com as a free CDN. You can use something else as a CDN, but the main point here is we don’t want to deal with the assets just because of the swagger UI.
Lastly, we need to add the swagger resource to the routes.
If you enter the http://localhost:3000/swagger address, you must be able to see the Swagger UI that takes the JSON file from /apidocs endpoint and provides the visual environment to test API endpoints and resources.
You will see the user creation endpoint in the Swagger UI, but we didn’t document the possible responses and response payloads for the endpoint. Let’s try to complete the missing parts with adding 201 (created) and 422 (unprocessable entity) responses to the UsersController class in the swagger folder.
We referenced to User, Meta, and Error classes to define the structure of the response payloads.
With the last change, rubocop warns us about too long blocks for the swagger classes, but since it’s the nature of the swagger-blocks DSL, we don’t need to maintain this rule in swagger related classes. You can disable the swagger folder from this rule as follows.
Now, we can start working on the User payload.
We also need to create the Meta model that we will also use for other API endpoints.
Then, we can also define the Error payload for the swagger documentation.
field_name_one and field_name_two refers to the attributes of the model. Let’s say for the User model email and password might replace the fields of the error keys.
We will also add those classes to the SWAGGERED_CLASSES in ApidocsController class.
If you enter the http://localhost:3000/swagger address again, you must be able to see also the possible responses with payloads. Finally, the API documentation with Swagger UI is up and running.
In this chapter, we completed the integration of Swagger UI and missing documentation classes that we use with swagger-blocks. You can find the source code of bookmarker application on github. You can also find the previous chapter here.
Thank you for reading! If you want to be notified when I publish a new chapter, you can follow me on twitter.