I have REST API project for which I need to generate documentation. I’ve looked into phoenix_swagger | Hex . However, as I’ve found out, it requires adding Elixir code right next to each API function: swagger_path :index do get "/api/users" summary "List users" description "List all u…

There is GitHub - open-api-spex/open_api_spex: Open API Specifications for Elixir Plug applications · GitHub , the up-to-date library for generation of openapi docs, it does more things automatically, however you will still need to describe the operation.

I think most people consider it a big advantage to have the docs next to the function, since they change together. I agree the phoenix_swagger DSL feels a bit “intrusive,” I prefer to use module attributes and build the open_api JSON from those. I built docout to make it easier to use custom notati…

I really like the rswag approach of integrating with the test interface, seems like the most natural place to have the docs and I’m surprised none of the Elixir projects have taken that direction.

I used rswag in my last major Rails project and while it’s nice having the little extra guarantee than your docs are accurate, I still prefer having docs next to the endpoint that I’m documenting, especially since Elixir supports such highly structured docs. And if you really want to guarantee accur…

[image] tfwright: And if you really want to guarantee accuracy you need to add a lot of extra assertions and if that kind of guarantee is not really necessary there’s not nearly as much advantage to coupling your doc generation to tests. I’m sure this is true, when I’ve used it it’s been eith…

But it uses the same approach: a lot of code-description next to each end point, right in the Elixir code. There’s no way to go around this, right? What I want is to keep the description of each REST API endpoint somewhere aside, in a separate file or files.

Why not just maintain your own json spec then? A good chunk of the functionality of these libraries is consolidating your Elixir function docs into a single OpenApi document. If you won’t want your spec in Elixir just build it in json or yaml or whatever?

[image] tfwright: Why not just maintain your own json spec then? What are the upsides of this?

Ability to generate dynamic web documentation of your API. Some tools even allow baking requests to the API from the web page where the documentation is.

Re-read 2-3 the previous responses

Generating REST API docs by Swagger

Questions & Help Questions

managua1902 August 27, 2023, 6:24pm 9

What are the upsides of this?