What do you use for endpoint documentation?

Phoenix Forum Chat / Discussions
,
1

Hi folks,

I’m wondering what do you use to document your Phoenix endpoints?
Is there anything that exists to be somehow connected to your views/controller and infer based on the modules used the content of the endpoint?

1 Like
2

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.

1 Like
3

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.

2 Likes
4

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.

3 Likes
5

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 :roll_eyes:

6

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.

3 Likes
7

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

8

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