Library to generate Api Docs in elixir

https://github.com/elixir-lang/ex_doc

I’m not sure if that is what @nishanthg92 wants.

The example he mentions does generate documentation about a serverside API. So I think this is much more related to phoenix than elixir. If @nishanthg92 does confirm, I’ll move the post to the phoenix section.

Yes please..

apiDoc supports Elixir comment syntax:

@apidoc """
@api {get} /user/:id Request User information
@apiName GetUser
@apiGroup User

@apiParam {Number} id Users unique ID.

@apiSuccess {String} firstname Firstname of the User.
@apiSuccess {String} lastname  Lastname of the User.
"""
def get_user(conn, %{"id" => id} = params) do
  # do something here
end

But you need Node.js to generate it:

$ npm install apidoc -g
$ apidoc -i lib/ -o doc/

Thank you! This comes in handy for a go-project of mine which I have to implement for the university. Cool that there is something available which is pretty agnostic to the host language!

@bobbypriambodo Just wanted to say thank you for the link to apiDoc. I was just looking for something like this the other day as a REST API is usually not suited well for standard ExDoc documentation because it’s something you access from an external source, not Elixir itself. apiDoc looks like exactly what I need, inline documentation is really easy to read and keep maintained.

Would be pretty awesome to see an extension of mix phx.routes that produces such documentation; phoenix can introspect to your routes, so having a way to markup the routing so it could produce this as well, preventing the need to discover other tooling, would be quite nifty.

The reason this could be worth the effort, besides the nice “batteries included” benefit, is that it could be extended to also include information about e.g. channels.

That said, the last time I did a big node project we used apidoc and it is indeed super nifty, particularly the “try it live” forms it generates.

I use phoenix_swagger to generate an API spec from the code, then use bureaucrat to merge example API request/responses with the swagger into markdown files. Compile the markdown to HTML with a static site generator and copy to the priv/static dir of the Phoenix app.

Now the app serves its own docs that are always up to date and have tested examples. There’s a swagger-ui for interactive requests.

Also if your API is GraphQL based, Absinthe in Elixir generates standard GraphQL documentation via your documentation given to it.

How does Absinthe generate this documentation? What is the command to generate the docs?