xcribe - GitLite

KO | EN

gitlite — search

#javascript #python #hacktoberfest #ai #typescript #golang #machine-learning #deep-learning #linux #docker #java #cli #pytorch #security

xcribe

(★ 61)

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

File Explorer

Download Latest Version (.zip)

- - ci.yml
- PULL_REQUEST_TEMPLATE.md
- check_version.exs
- config.exs
- test.exs
- test_support.exs
- serving_doc.md
- - config.ex
  - conn_parser.ex
  - content_decoder.ex
  - document.ex
  - exceptions.ex
  - formatter.ex
  - information.ex
  - json.ex
  - json_schema.ex
  - recorder.ex
  - writter.ex
- xcribe.ex
- - absolute-path.js
  - favicon-16x16.png
  - favicon-32x32.png
  - oauth2-redirect.html
  - swagger-ui-bundle.js
  - swagger-ui-bundle.js.map
  - swagger-ui-standalone-preset.js
  - swagger-ui-standalone-preset.js.map
  - swagger-ui.css
  - swagger-ui.css.map
  - swagger-ui.js
  - swagger-ui.js.map
- - swagger_ui.eex
- - api_blueprint_example.apib
  - application.ex
  - conn_case.ex
  - endpoint.ex
  - information.ex
  - requests_generator.ex
  - swagger_example.json
  - web_router.ex
- - config_test.exs
  - conn_parser_test.exs
  - content_decoder_test.exs
  - document_test.exs
  - formatter_test.exs
  - information_test.exs
  - json_schema_test.exs
  - recorder_test.exs
  - writter_test.exs
- test_helper.exs
- xcribe_test.exs
.credo.exs
.formatter.exs
.gitignore
.tool-versions
CHANGELOG.md
CODE_OF_CONDUCT.md
CONTRIBUTING.md
coveralls.json
guide.md
LICENSE
Makefile
mix.exs
mix.lock
README.md

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Xcribe

[![GitHub Workflow Status](https://img.shields.io/github/workflow/status/Finbits/xcribe/CI?style=flat-square)](https://github.com/Finbits/xcribe/actions?query=workflow%3ACI)
[![Hex.pm](https://img.shields.io/hexpm/v/xcribe?style=flat-square)](https://hex.pm/packages/xcribe)
[![Hex.pm](https://img.shields.io/hexpm/l/xcribe?style=flat-square)](https://hex.pm/packages/xcribe)
[![Hex.pm](https://img.shields.io/hexpm/dt/xcribe?style=flat-square)](https://hex.pm/packages/xcribe)
[![codecov](https://img.shields.io/codecov/c/github/Finbits/xcribe?style=flat-square)](https://codecov.io/gh/Finbits/xcribe)

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

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

Update deps

```sh
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:

```elixir
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

```elixir
  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

```elixir
 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

```elixir
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

```elixir
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

```elixir
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`

```sh
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](https://apiblueprint.org/tools.html#renderers)

If Swagger format is configured, [Swagger UI](https://swagger.io/tools/swagger-ui/download/) 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

```elixir
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](documentation/serving_doc.md)

## Contributing

[Contributing Guide](CONTRIBUTING.md)

## License

[Apache License, Version 2.0](LICENSE) © [Finbits](https://github.com/Finbits)