PhoenixSwagger.JsonApi (phoenix_swagger v0.8.3) View Source

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

Link to this section Summary

Functions

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

Defines an attribute in a JSON-API schema.

attributes(model, block)

Defines a block of attributes for a JSON-API resource.

link(model, name, description)

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.

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

Defines a relationship.

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

single(resource)

Defines a schema for a top level json-api document with a single primary data resource.

Link to this section 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.

attributes(model, block)

(macro)

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.

Examples

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)

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 \\ [])

Specs

relationship(
  %PhoenixSwagger.Schema{
    "$ref": term(),
    additionalProperties: term(),
    allOf: term(),
    default: term(),
    description: term(),
    discriminator: term(),
    enum: term(),
    example: term(),
    exclusiveMaximum: term(),
    exclusiveMinimum: term(),
    format: term(),
    items: term(),
    maxItems: term(),
    maxLength: term(),
    maxProperties: term(),
    maximum: term(),
    minItems: term(),
    minLength: term(),
    minProperties: term(),
    minimum: term(),
    multipleOf: term(),
    pattern: term(),
    properties: term(),
    readOnly: term(),
    required: term(),
    title: term(),
    type: term(),
    uniqueItems: term(),
    "x-nullable": term()
  },
  name :: atom(),
  [option]
) :: %PhoenixSwagger.Schema{
  "$ref": term(),
  additionalProperties: term(),
  allOf: term(),
  default: term(),
  description: term(),
  discriminator: term(),
  enum: term(),
  example: term(),
  exclusiveMaximum: term(),
  exclusiveMinimum: term(),
  format: term(),
  items: term(),
  maxItems: term(),
  maxLength: term(),
  maxProperties: term(),
  maximum: term(),
  minItems: term(),
  minLength: term(),
  minProperties: term(),
  minimum: term(),
  multipleOf: term(),
  pattern: term(),
  properties: term(),
  readOnly: term(),
  required: term(),
  title: term(),
  type: term(),
  uniqueItems: term(),
  "x-nullable": term()
}
when option: {:type, relationship_type} | {:nullable, boolean()},
     relationship_type: :has_one | :has_many

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

resource(list)

(macro)

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

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