phoenix_swagger v0.7.0 PhoenixSwagger.JsonApi

This module defines a DSL for defining swagger definitions in a JSON-API conformant format.

Examples

use PhoenixSwagger

def swagger_definitions do
  %{
    UserResource: JsonApi.resource do
      description "A user that may have one or more supporter pages."
      attributes do
        phone :string, "Users phone number"
        full_name :string, "Full name"
        user_updated_at :string, "Last update timestamp UTC", format: "ISO-8601"
        user_created_at :string, "First created timestamp UTC"
        email :string, "Email", required: true
        birthday :string, "Birthday in YYYY-MM-DD format"
        address Schema.ref(:Address), "Users address"
      end
      link :self, "The link to this user resource"
      relationship :posts
    end,
    Users: JsonApi.page(:UserResource),
    User: JsonApi.single(:UserResource)
  }
end

swagger_path :index do
  get "/api/v1/users"
  paging size: "page[size]", number: "page[number]"
  response 200, "OK", Schema.ref(:Users)
end

Summary

Functions

Defines an attribute in a JSON-API schema

Defines a link with name and description

Defines a schema for a top level json-api document with an array of resources as primary data. The given resource should be the name of a JSON-API resource defined with the resource/1 macro

Defines a relationship Optionally can pass type: :has_many or type: :has_one to determine whether to structure the relationship as an object or array. Defaults to :has_one

Defines a schema for a top level json-api document with a single primary data resource. The given resource should be the name of a JSON-API resource defined with the resource/1 macro

Macros

Defines a block of attributes for a JSON-API resource. Within this block, each function call will be translated into a call to the PhoenixSwagger.JsonApi.attribute function

Defines a schema for a JSON-API resource, without the enclosing top-level document

Functions

attribute(model, name, type, description, opts \\ [])

Defines an attribute in a JSON-API schema.

Name, type and description are accepted as positional arguments, but any other schema properties can be set through the trailing keyword arguments list. As a convenience, required: true can be passed in the keyword args, causing the name of this attribute to be added to the “required” list of the attributes schema.

link(model, name, description)

Defines a link with name and description

page(resource)

Defines a schema for a top level json-api document with an array of resources as primary data. The given resource should be the name of a JSON-API resource defined with the resource/1 macro

relationship(model, name, opts \\ [])

Defines a relationship Optionally can pass type: :has_many or type: :has_one to determine whether to structure the relationship as an object or array. Defaults to :has_one

single(resource)

Defines a schema for a top level json-api document with a single primary data resource. The given resource should be the name of a JSON-API resource defined with the resource/1 macro

Macros

attributes(model, block)

Defines a block of attributes for a JSON-API resource. Within this block, each function call will be translated into a call to the PhoenixSwagger.JsonApi.attribute function.

Example

description("A User")
attributes do
  name :string, "Full name of the user", required: true
  dateOfBirth :string, "Date of Birth", format: "ISO-8601", required: false
end

translates to:

description("A User")
|> attribute(:name, :string, "Full name of the user", required: true)
|> attribute(:dateOfBirth, :string, "Date of Birth", format: "ISO-8601", required: false)
resource(list)

Defines a schema for a JSON-API resource, without the enclosing top-level document.