Rolodex v0.5.0 Rolodex
Rolodex generates documentation for your Phoenix API.
Rolodex inspects a Phoenix Router and transforms the @doc
annotations on your
controller actions into documentation in the format of your choosing.
Rolodex.run/1
encapsulates the full documentation generation process. When
invoked, it will:
- Traverse your Phoenix Router
- Collect documentation data for the API endpoints exposed by your router
- Serialize the data into a format of your choosing (e.g. Swagger JSON)
- Write the serialized data out to a destination of your choosing.
Rolodex can be configured in the config/
files for your Phoenix project. See
Rolodex.Config
for more details on configuration options.
Features and resources
- Reusable schemas - See
Rolodex.Schema
for details on how define reusable parameter schemas. SeeRolodex.RequestBody
for details on how to use schemas in your API request body definitions. SeeRolodex.Response
for details on how to use schemas in your API response definitions. - Structured annotations - See
Rolodex.Route
for details on how to format annotations on your API route action functions for the Rolodex parser to handle - Generic serialization - The
Rolodex.Processor
behaviour encapsulates the basic steps needed to serialize API metadata into documentation. Rolodex ships with a valid Swagger JSON processor (see:Rolodex.Processors.Swagger
) - Generic writing - The
Rolodex.Writer
behaviour encapsulates the basic steps needed to write out formatted docs. Rolodex ships with a file writer ( see:Rolodex.Writers.FileWriter
)
High level example
# Your Phoenix router
defmodule MyRouter do
pipeline :api do
plug MyPlug
end
scope "/api" do
pipe_through [:api]
get "/test", MyController, :index
end
end
# Your controller
defmodule MyController do
@doc [
auth: :BearerAuth,
headers: ["X-Request-ID": uuid],
query_params: [include: :string],
path_params: [user_id: :uuid],
body: MyRequestBody,
responses: %{200 => MyResponse},
metadata: [public: true],
tags: ["foo", "bar"]
]
@doc "My index action"
def index(conn, _), do: conn
end
# Your request body
defmodule MyRequestBody do
use Rolodex.RequestBody
request_body "MyRequestBody" do
desc "A request body"
content "application/json" do
schema MySchema
example :request, %{id: "123", name: "Ada Lovelace"}
end
end
end
# Your response
defmodule MyResponse do
use Rolodex.Response
response "MyResponse" do
desc "A response"
content "application/json" do
schema MySchema
example :response, %{id: "123", name: "Ada Lovelace"}
end
end
end
# Your schema
defmodule MySchema do
use Rolodex.Schema
schema "MySchema", desc: "A schema" do
field :id, :uuid
field :name, :string, desc: "The name"
end
end
# Your Rolodex config
defmodule MyConfig do
use Rolodex.Config
def spec() do
[
title: "MyApp",
description: "An example",
version: "1.0.0",
router: MyRouter
]
end
def auth_spec() do
[
BearerAuth: [
type: "http",
scheme: "bearer"
]
]
end
def pipelines_spec() do
[
api: [
headers: ["Include-Meta": :boolean]
]
]
end
end
# In mix.exs
config :rolodex, module: MyConfig
# Then...
Application.get_all_env(:rolodex)[:module]
|> Rolodex.Config.new()
|> Rolodex.run()
# The JSON written out to file should look like
%{
"openapi" => "3.0.0",
"info" => %{
"title" => "MyApp",
"description" => "An example",
"version" => "1.0.0"
},
"paths" => %{
"/api/test" => %{
"get" => %{
"security" => [%{"BearerAuth" => []}],
"metadata" => %{"public" => true},
"parameters" => [
%{
"in" => "header",
"name" => "X-Request-ID",
"schema" => %{
"type" => "string",
"format" => "uuid"
}
},
%{
"in" => "path",
"name" => "user_id",
"schema" => %{
"type" => "string",
"format" => "uuid"
}
},
%{
"in" => "query",
"name" => "include",
"schema" => %{
"type" => "string"
}
}
],
"responses" => %{
"200" => %{
"$ref" => "#/components/responses/MyResponse"
}
},
"requestBody" => %{
"type" => "object",
"properties" => %{
"id" => %{"type" => "string", "format" => "uuid"}
}
},
"tags" => ["foo", "bar"]
}
}
},
"components" => %{
"requestBodies" => %{
"MyRequestBody" => %{
"description" => "A request body",
"content" => %{
"application/json" => %{
"schema" => %{
"$ref" => "#/components/schemas/MySchema"
},
"examples" => %{
"request" => %{"id" => "123", "name" => "Ada Lovelace"}
}
}
}
}
},
"responses" => %{
"MyResponse" => %{
"description" => "A response",
"content" => %{
"application/json" => %{
"schema" => %{
"$ref" => "#/components/schemas/MySchema"
},
"examples" => %{
"response" => %{"id" => "123", "name" => "Ada Lovelace"}
}
}
}
}
},
"schemas" => %{
"MySchema" => %{
"type" => "object",
"description" => "A schema",
"properties" => %{
"id" => %{"type" => "string", "format" => "uuid"},
"name" => %{"type" => "string", "description" => "The name"}
}
}
},
"securitySchemes" => %{
"BearerAuth" => %{
"type" => "http",
"scheme" => "bearer"
}
}
}
}
Link to this section Summary
Functions
Generates a list of route docs and a map of response schemas. Passes both into the configured processor to generate the documentation JSON to be written to file
Inspects the request and response parameter data for each Rolodex.Route
.
From these routes, it collects a unique list of Rolodex.RequestBody
,
Rolodex.Response
, and Rolodex.Schema
references. The serialized refs will
be passed along to a Rolodex.Processor
behaviour
Inspects the Phoenix Router provided in your Rolodex.Config
. Iterates
through the list of routes to generate a Rolodex.Route
for each. It will
filter out any route(s) that match the filter(s) you provide in your config
Runs Rolodex and writes out documentation to the specified destination
Link to this section Functions
generate_documentation(config)
generate_documentation(Rolodex.Config.t()) :: String.t()
generate_documentation(Rolodex.Config.t()) :: String.t()
Generates a list of route docs and a map of response schemas. Passes both into the configured processor to generate the documentation JSON to be written to file.
generate_refs(routes)
generate_refs([Rolodex.Route.t()]) :: map()
generate_refs([Rolodex.Route.t()]) :: map()
Inspects the request and response parameter data for each Rolodex.Route
.
From these routes, it collects a unique list of Rolodex.RequestBody
,
Rolodex.Response
, and Rolodex.Schema
references. The serialized refs will
be passed along to a Rolodex.Processor
behaviour.
generate_routes(config)
generate_routes(Rolodex.Config.t()) :: [Rolodex.Route.t()]
generate_routes(Rolodex.Config.t()) :: [Rolodex.Route.t()]
Inspects the Phoenix Router provided in your Rolodex.Config
. Iterates
through the list of routes to generate a Rolodex.Route
for each. It will
filter out any route(s) that match the filter(s) you provide in your config.
run(config)
run(Rolodex.Config.t()) :: :ok | {:error, any()}
run(Rolodex.Config.t()) :: :ok | {:error, any()}
Runs Rolodex and writes out documentation to the specified destination