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

Defines an attribute in a JSON-API schema.

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 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 JSON-API resource, without the enclosing top-level document.

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

Link to this section Functions

Link to this function

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

View Source

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 to this macro

attributes(model, block)

View Source (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.

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)
Link to this function

link(model, name, description)

View Source

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

Link to this function

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

View Source

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(),
    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(),
  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

Link to this macro

resource(list)

View Source (macro)

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

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