Library to generate Api Docs in elixir

I am basically from symfony background, i am new to elixir. In symfony there is ApiDocBundle which allows me to generate a decent documentation for my APIs. Likewise is there any method in Phoenix Elixir ??

1 Like
1 Like

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/
4 Likes

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.

1 Like

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.

3 Likes

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

4 Likes

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

It does it via your schema definition, like if you want to document an argument on a field (to use a specific example):

field do
  arg :size, :integer, description: "The size of the thing"
  arg :name, :string, description: "The desired name of the thing"
end

Or document an overall ‘type’:

@desc """
The [`DateTime`](https://hexdocs.pm/elixir/DateTime.html) scalar type represents a date and time in the UTC
timezone. The DateTime appears in a JSON response as an ISO8601 formatted
string, including UTC timezone ("Z"). The parsed date and time string will
be converted to UTC and any UTC offset other than 0 will be rejected.
"""
scalar :datetime, name: "DateTime" do
  serialize &DateTime.to_iso8601/1
  parse &parse_datetime/1
end

Etc… It’s all the docs (though perhaps a dedicated section for just this purpose, if it doesn’t already exist, would be useful). :slight_smile:

See: https://hexdocs.pm/absinthe/Absinthe.Schema.Notation.html#description/1

Is Graphiql the only tool to explore GraphQL schemas? Or is there some way to generate static documentation pages?

I havn’t looked into static pages (that’s not really the graphql way) but I don’t doubt such things exist to generate them from schema’s and their documentation.

Absinthe can export the GraphQL schema though, it has a mix task for it. :slight_smile:

mix absinthe.schema.json --json-codec Jason --schema Blah --pretty
3 Likes

https://github.com/2fd/graphdoc and https://github.com/gjtorikian/graphql-docs are the two that crop up easiest from a Google search. I just investigated using graphdoc and it was pretty easy to setup, these are the basic steps:

npm install -g @2fd/graphdoc
mix absinthe.schema.json --schema MySchema --pretty path/to/schema.json
graphdoc -s path/to/schema.json -o doc/schema

Although instead of actually using absinthe.schema.json I grabbed the same schema that Graphiql downloads

5 Likes

Thanks, this is what I was looking for!

2 Likes

Oh hey cool! Thanks for the links!!

2 Likes