Repository files navigation

Xcribe is a doc generator for Rest APIs built with Phoenix.The documentation is generated by the test specs.

Currently both Blueprint and Swagger (OpenAPI Spec 3.0) syntax are supported. In the future other formats willbe added.

Add Xcribe to your application

mix.exs

defdepsdo[{:xcribe,"~> 0.7.12"}]end

Update deps

mix deps.get

Xcribe requires that you create an "Information Module". This module definesthe custom information about your API documentation.

Create a module that usesXcribe.Information as:

defmoduleYourAppWeb.Support.DocInformationdouseXcribe.Informationxcribe_infodoname"Your awesome API"description"The best API in the world"host"http://your-api.us"endend

Add a new configuration with the created module

config/test.exs

config:xcribe,information_source:YourAppWeb.Support.DocInformation,format::swagger,output:"app_doc.json"

Next, in yourtest/test_helper.exs you should configure ExUnit to use Xcribeformatter. You would probably like to keep the default ExUnit.CLIFormatter aswell.

test/test_helper.exs

ExUnit.start(formatters:[ExUnit.CLIFormatter,Xcribe.Formatter])

Xcribe generates documentation fromPlug.Conn struct used on your tests. Todocument a route you need pass theconn struct to macrodocument.

First you need importXcribe.Document macro in yourConnCase file (usally located in/test/support/conn_case.ex).Doing that,document/2 macro will be available into your test specs.

/test/support/conn_case.ex

defmoduleYourAppWeb.ConnCasedouseExUnit.CaseTemplateusingdoquotedo...# import Xcribe `document/2` macroimportXcribe.Document...endendend

Now in your tests you should call the macrodocument with the conn struct

test"get posts",%{conn:conn}doresponse=conn|>get("/posts")|>document()|>json_response(200)assertresponse==[]end

you can specify a custom request name by passing an argumentas: "description"to the macro

test"get posts",%{conn:conn}doresponse=conn|>get("/posts")|>document(as:"index request")|>json_response(200)assertresponse==[]end

To generate the doc file runmix test with an env varXCRIBE_ENV=true

XCRIBE_ENV=true mixtest

A fileapi_doc.apib will be created with the documentation if ApiBlueprint is configured. If Swagger format is chosen, thenopenapi.json file will be created.

The output file is write in Blueprint sintax. To render to HTML you can use thetools listed atAPIBLUEPRINT.ORG

If Swagger format is configured,Swagger UI can be used to display Swagger documentation.

You can add this configurations to yourconfig/test.ex

• information_source: the module with doc information
• output: a custom name to the output file
• format: ApiBlueprint or Swagger formats
• env_var: a custom name to the env to active Xcribe.Formatter
• json_library: The library to be used for json decode/encode.
• serve: Enables Xcribe serve mode. See more inServing doc session.

Example

config:xcribe,[information_source:YourAppWeb.Information,output:"API-DOCUMENTATION.apib",format::api_blueprint# or :swagger,env_var:"DOC_API",json_library:Jason]

Serve doc

Contributing Guide

Apache License, Version 2.0 ©Finbits