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.

Open API Spec 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

--

--

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
deepak sharma

deepak sharma

Senior Programmer with 10 years of industry experience. I love to learn and share new things. I have worked on varied tech stacks like Python flask, Elixir etc.