ProductPromotion
Logo

Elixir

made by https://0x3d.site

GitHub - Danielwsx64/xcribe: XCribe is a doc generator for Rest APIs built with Phoenix. The documentation is generated by the test specs.
XCribe is a doc generator for Rest APIs built with Phoenix. The documentation is generated by the test specs. - Danielwsx64/xcribe
Visit Site

GitHub - Danielwsx64/xcribe: XCribe is a doc generator for Rest APIs built with Phoenix. The documentation is generated by the test specs.

GitHub - Danielwsx64/xcribe: XCribe is a doc generator for Rest APIs built with Phoenix. The documentation is generated by the test specs.

Xcribe

GitHub Workflow Status Hex.pm Hex.pm Hex.pm codecov

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 will be added.

Installation

Add Xcribe to your application

mix.exs

def deps do
  [
    {:xcribe, "~> 0.7.12"}
  ]
end

Update deps

mix deps.get

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

Create a module that uses Xcribe.Information as:

defmodule YourAppWeb.Support.DocInformation 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

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 your test/test_helper.exs you should configure ExUnit to use Xcribe formatter. You would probably like to keep the default ExUnit.CLIFormatter as well.

test/test_helper.exs

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

Usage

Xcribe generates documentation from Plug.Conn struct used on your tests. To document a route you need pass the conn struct to macro document.

First you need import Xcribe.Document macro in your ConnCase 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

defmodule YourAppWeb.ConnCase do
  use ExUnit.CaseTemplate

  using do
    quote do

     ...

      # import Xcribe `document/2` macro
      import Xcribe.Document

     ...

    end
  end
end

Now in your tests you should call the macro document with the conn struct

test "get posts", %{conn: conn} do

  response =
    conn
    |> get("/posts")
    |> document()
    |> json_response(200)

  assert response == []
end

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

test "get posts", %{conn: conn} do

  response =
    conn
    |> get("/posts")
    |> document(as: "index request")
    |> json_response(200)

  assert response == []
end

To generate the doc file run mix test with an env var XCRIBE_ENV=true

XCRIBE_ENV=true mix test

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

Rendering HTML

The output file is write in Blueprint sintax. To render to HTML you can use the tools listed at APIBLUEPRINT.ORG

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

Configure

You can add this configurations to your config/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 in Serving 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 documentation

Serve doc

Contributing

Contributing Guide

License

Apache License, Version 2.0 © Finbits

Articles
to learn more about the elixir concepts.

Resources
which are currently available to browse on.

mail [email protected] to add your project or resources here 🔥.

FAQ's
to know more about the topic.

mail [email protected] to add your project or resources here 🔥.

Queries
or most google FAQ's about Elixir.

mail [email protected] to add more queries here 🔍.

More Sites
to check out once you're finished browsing here.

0x3d
https://www.0x3d.site/
0x3d is designed for aggregating information.
NodeJS
https://nodejs.0x3d.site/
NodeJS Online Directory
Cross Platform
https://cross-platform.0x3d.site/
Cross Platform Online Directory
Open Source
https://open-source.0x3d.site/
Open Source Online Directory
Analytics
https://analytics.0x3d.site/
Analytics Online Directory
JavaScript
https://javascript.0x3d.site/
JavaScript Online Directory
GoLang
https://golang.0x3d.site/
GoLang Online Directory
Python
https://python.0x3d.site/
Python Online Directory
Swift
https://swift.0x3d.site/
Swift Online Directory
Rust
https://rust.0x3d.site/
Rust Online Directory
Scala
https://scala.0x3d.site/
Scala Online Directory
Ruby
https://ruby.0x3d.site/
Ruby Online Directory
Clojure
https://clojure.0x3d.site/
Clojure Online Directory
Elixir
https://elixir.0x3d.site/
Elixir Online Directory
Elm
https://elm.0x3d.site/
Elm Online Directory
Lua
https://lua.0x3d.site/
Lua Online Directory
C Programming
https://c-programming.0x3d.site/
C Programming Online Directory
C++ Programming
https://cpp-programming.0x3d.site/
C++ Programming Online Directory
R Programming
https://r-programming.0x3d.site/
R Programming Online Directory
Perl
https://perl.0x3d.site/
Perl Online Directory
Java
https://java.0x3d.site/
Java Online Directory
Kotlin
https://kotlin.0x3d.site/
Kotlin Online Directory
PHP
https://php.0x3d.site/
PHP Online Directory
React JS
https://react.0x3d.site/
React JS Online Directory
Angular
https://angular.0x3d.site/
Angular JS Online Directory