Xcribe v0.7.4 Xcribe View Source
Xcribe is a library for API documentation. It generates docs from your test specs.
Xcribe use Plug.Conn
struct to fetch information about requests and use them
to document your API. You must give requests examples (from your tests ) to Xcribe
be able to document your routes.
Each connection sent to documenting in your tests is parsed. Is expected that
connection has been passed through the app Endpoint
as a finished request.
The parser will extract all needed info from Conn
and uses app Router
for additional information about the request.
The attribute description
may be given at document
macro call with the
option :as
:
test "test name", %{conn: conn} do
...
document(conn, as: "description here")
...
end
If no description is given the current test description will be used.
API information
You must provide your API information by creatint a mudule that use
Xcribe.Information
macros.
The required info are:
name
- a name for your API.description
- a description about your API.host
- your API host url
This information is set by Xcribe macros inside the block xcribe_info
. eg:
defmodule YourModuleInformation do
use Xcribe.Information
xcribe_info do
name "Your awesome API"
description "The best API in the world"
host "http://your-api.us"
end
end
See Xcribe.Information
for more details about custom information.
JSON
Xcribe uses the same json library configured for Phoenix to handle json content. you can configure xcribe to use your preferred library. Poison and Jason are the most popular json libraries common used in Elixir and Xcribe works fine with both.
Configuration
You must configure at least the information_source
and format
for basic use.
eg
config :xcribe,
information_source: YourApp.YouModuleInformation,
format: :swagger
Available configurations:
:information_source
- Module that implementsXcribe.Information
with API information. It's required.:output
- The name of file output with generated configuration. Default value changes by the format, 'api_blueprint.apib' for Blueprint and 'app_doc.json' for swagger.:format
- Format to generate documentation, allowed:api_blueprint
and:swagger
. Default:api_blueprint
.:env_var
- Environment variable name for active Xcribe documentation generator. Default isXCRIBE_ENV
.:json_library
- The library to be used for json decode/encode (Jason and Poison are supported). The default is the same asPhoenix
configuration.:serve
- Enable Xcribe serve mode. Defaultfalse
. See moreServing doc