Library to generate Api Docs in elixir

Phoenix Forum Questions / Help
,
1

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
2
1 Like
3

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.

4

Yes pleaseā€¦

5

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
6

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!

7

@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.

8

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
9

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.

4 Likes
10

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

4 Likes
11

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

12

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

13

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

14

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
15

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
16

Thanks, this is what I was looking for!

2 Likes
17

Oh hey cool! Thanks for the links!!

2 Likes