What do you use for endpoint documentation?

I don’t know if I got your question right.. Do you mean your routes? Do you want a way to organize all your routes in a central manner so people can easily see all the routes and have easy access to its documentation without needing to know where to controller’s files are located?

If so, what I do is first create a pages/API.md file in the root of the project, with something like this:

# APIs

## context 1

  > [/api/v1/context_1/my_api_call](`CoreWeb.V1.Context1Controller.my_api_call/2`)
  > [/api/v1/context_1/my_other_api_call](`CoreWeb.V1.Context1Controller.my_other_api_call/2`)

Then change mix.exs with:

def project do
  ...
  docs: docs()
end

defp docs do
  [
    main: "api",
    extras: ["pages/API.md"]
  ]
end

And then, finally, at the Context1Controller file, I simply use @doc to document the functions:

  @doc """
  blablabla
  """
  def my_api_call(conn, _), do: ...

  @doc """
  blablabla
  """
  def my_other_api_call(conn, _), do: ...

This will generate a Page in Exdocs.

Never used another tool other than Swagger. Doing it in Elixir though - in contrast with something that is statically typed - it’s a little pain in the ass to configure because we don’t have those guarantees to infer from.

I’m also not sure if I really understand your goal.
For API documentation I do in one of my project pass the Plug conn in every API Endpoint test to a custom Docs.WebAPI.generate_doc(conn, description) function. This function simplified formulated appends the documentation to a markdown file - also hooked then as docs - extras into the ExDocs documentation.

Means my solution is based on: github.com/api-hogs/bureaucrat

The result could be something like: developer.stadtmacherei-salzburg.at/backend/live/web_api_endpoints.html
By the way this project is nearly on ice - so if you find something totally done wrong - anyway let me know.

Well we tried something like this but it’s quite tedious as you said. And because we (at work) don’t know all the nuggets available, I prefer ask the community what they do, because it’s a fact that everybody loves to write docs

I got the ok to open source some openAPI work were doing at work; it will take an openApi (swagger) y’all and generate a router for you, so you embed your docs in the openApi format.

Yep, I’d be glad to check this out!

This looks great. Unfortunately, we’ve got not enough tests to build the doc this way. Definitely, it’ll be a goal to reach.