OPEN API SPEC Elixir/Phoenix

Introduction

This document is like a training course for writing documentation for Rest APIs in Elixir. Nowadays Elixir is used widely to write HTTP applications. It has become necessary for developers to write documentation for REST APIs.

The library we will use is called Open API Spex. This library generates an Open API Specification file that can be rendered anywhere.

Using Open API Spex(OAS)

Open API Spex is a library used to generate an Open API specification in Elixir. Each OAS property maps to an Open API Spec property and most things render directly.

The following screenshot represents an example of writing the Open API for a home page request.

Let's try to understand each field above.

1. operation_id: This is a reference that OAS uses when building a JSON document. It will also be used in hyperlinks within the final documentation. This is a required field.
2. summary: This field defines the name of the endpoint on the documentation website. This is a required field.
3. description: This field defines the description text for the endpoint. This is a required field.
4. parameters: Query and path parameters are listed here. You can write them into the decorator, or you can reference them from a schemata file.
5. responses: A request body is for sending a payload request object. The first part of this request “HomePageResponse” is displayed in the interface as the name of the object. The second part “application/json” tells the server the header context type. This is also displayed on the documentation website. The last part is the reference to the object.
6. request_body: The responses can be listed as labels or codes.
7. security: You can define the security and scope of the endpoint.
8. tags: This is the name of the group where this endpoint should appear on the documentation website.
9. deprecated: Adds a field to deprecate a controller operator if the endpoint is deprecated.

Conclusion

With the knowledge above you will have a general idea about writing API documentation. I hope this adds some value and if you want to go deeper into writing all kinds of API, you can visit Open Api Spex. Let me know in the comments if you want a similar article explaining some complex APIs. You can post an example API in the comment section and I will try to write the Open API spec for it.

Thank you for reading