Documenting your endpoints

As I said before, OpenAPI is language agnostic, so you can document your API endpoints individually, write that OpenAPI document yourself, and generate your Go code from that. Also, you can write your code, including some comments, and use a tool that produces an OpenAPI document from your source code.

The third option would be generating both and manually keeping them in sync. All the approaches have interesting benefits and drawbacks, so let’s explore them.

Writing code and OpenAPI documents

Writing both code and OpenAPI documents is a way that some people prefer because it gives us fine-grained control over the OpenAPI document generated and the code generated. Also, it doesn’t require any extra dependencies to get this working. However, as often happens, with more control comes more responsibility. This approach requires you to keep code and OpenAPI documents in sync, which can be challenging. This approach eventually requires...