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 users in the database" tag "Users" produces "application/json" response(200, "OK", Schema.ref(:UsersResponse), example: %{ data: [ %{ id: 1, count: 42, email: "some email", name: "some name", private: true, profile: "some profile", } ] } ) end def index(conn, _params) do users = Users.list_users() render(conn, "index.json", users: users) end This will greatly litter the code where it’ll be unnecessary, in my opinion. Is there other Elixir Swagger library which is up to date and usable? Or how else will I generate the REST API docs?

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 notation to convert function docs into documentation files (like an open_api.json) during the compilation phase.

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 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 also found rswag a little rough around the edges when it came to actually using it, since it needs to have a 1-1 DSL parity for every open_api feature, so it doesn’t take long into you run into things are not supported, or just really awkward to use. Of course back then it seemed like the open_api spec was more in flux than it is now.

[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 either for an externally-facing API, or where we’ve had separate mobile and backend teams who only ever interacted by API contract, both situations where accuracy was a very high priority. Edit: honestly, I don’t think I’d bother with swagger in a situation where that wasn’t the case, but obviously YMMV.

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

tfwright August 27, 2023, 11:40pm 12

It’s exactly what you’re asking for: