Generating REST API docs by Swagger

Questions / Help
, ,
1

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?

2

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

3

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.

4

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.

5

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.

6

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.

7

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.

8

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?

9

What are the upsides of this?

10

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.

11

Re-read 2-3 the previous responses

12

It’s exactly what you’re asking for:

1 Like
13

What are the downsides of the approach you’ve suggested then?

14

If you want to go from schema to router there’s apical.

https://hexdocs.pm/apical/Apical.html

15

How do you maintain multiple versions of the schema if they’re generated from the tests?

16

Well in rswag the API version is just one of the swagger annotations you put in your tests, it defaults to the first version (that you’ve defined in your swagger config) but when you have multiple versions then you just annotate your v1 tests to be for your v1 docs, v2 for v2, etc.