SwaggerDoc

The SwaggerDoc module provides a convenience task for generating Swagger API documentation for Phoenix and Ecto-based projects. This task has been created for Phoenix and Ecto 1.0 and greater.

Build Status

Getting Started

To use swaggerdoc with your projects, edit your mix.exs file and add it as a dependency:

defp deps do
  [{:swaggerdoc, "~> 0.0.1"}]
end

To execute the Mix task, simply type mix swagger:

hello_user$ mix swagger
Generating Swagger documentation...
Adding Ecto definitions...
Adding Phoenix Routes...
Writing JSON to file...
Finished generating Swagger documentation!

To view the generated Swagger in swagger-ui:

For a complete example, please see the examples section.

Config

SwaggerDoc's version and project information is configured in your config.exs files. The options are specified under the :swaggerdoc application.

config :swaggerdoc,
  swagger_version: "2.0"

Task Config

The following task-specific options are available:

Swagger Config

The following Swagger-specific options are available:

Here's an example from the sample HelloUser's config.exs:

config :swaggerdoc,
  swagger_version: "2.0",
  project_version: "1.0.0",
  project_name: "Hello User",
  project_desc: "The REST API for the Hello User",
  project_terms: "https://www.mozilla.org/en-US/MPL/2.0/",
  project_contact_name: "OpenAperture",
  project_contact_email: "openaperture@lexmark.com",
  project_contact_url: "http://openaperture.io",
  project_license_name: "Mozilla Public License, v. 2.0",
  project_license_url: "https://www.mozilla.org/en-US/MPL/2.0/",
  host: "openaperture.io",
  base_path: "/",
  schemes: ["https"],
  consumes: ["application/json"],
  produces: ["application/json"]

Default Behavior

The mix task is designed to scan for Ecto-specific Models and Phoenix-specific routes to attempt to generate an accurrate Swagger API object.

Converting Ecto Models into Swagger Definitions

Each Ecto Model that is identified (prescence of the schema method) is converted into a Definitions Object.

The conversion uses schema fields and updates them into schemas unde the Definitions Object. The following values are used to convert an Ecto schema type into a Swagger property type:

Looking at the HelloUser.User model:

  schema "users" do
    field :name, :string
    field :email, :string
    field :bio, :string
    field :number_of_pets, :integer

    timestamps
  end

The JSON output will look like:

    "definitions": {
      "HelloUser.User": {
        "properties": {
          "updated_at": {
            "type": "string",
            "format": "date-time"
          },
          "number_of_pets": {
            "type": "integer",
            "format": "int64"
          },
          "name": {
            "type": "string"
          },
          "inserted_at": {
            "type": "string",
            "format": "date-time"
          },
          "id": {
            "type": "integer",
            "format": "int64"
          },
          "email": {
            "type": "string"
          },
          "bio": {
            "type": "string"
          }
        }
      }
    }

Converting Phoenix Routes into Swagger Paths

The Phoenix Routes that is found via the Phoenix Router are converted into a Swagger Paths Object, each route becoming a Path Item. The Phoenix template paths are converted into Swagger path templates and each templated variable is converted into a Path paramter. All path parameters are assumed to be required and are of type string (except for parameters named id, which are assumed to be integers).

Response Definitions are generated, based on the HTTP verb associated with the operation:

Customized Behavior

The default behavior of the task may be improved by adding action-specific functions that provide the task more detail. As the task scans for Phoenix Routes, it will check for the prescense of a function named "swaggerdoc_#{route.controller.method}". If that function is present, the Map returned will be used in place of the default Swagger implementation. The map may consist of the following elements:

Contributing

To contribute to OpenAperture development, view our contributing guide