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
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.
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.
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)