phoenix_swagger v0.7.0 PhoenixSwagger.Path

Defines the swagger path DSL for specifying Controller actions. This module should not be imported directly, it will be automatically imported in the scope of a swagger_path macro body.

Examples

use PhoenixSwagger

swagger_path :index do
  get "/users"
  produces "application/json"
  paging
  parameter :id, :query, :integer, "user id", required: true
  tag "Users"
  response 200 "User resource" :User
  response 404 "User not found"
end

Summary

Functions

Adds a mime-type to the consumes list of the operation of a swagger %PathObject{}

Initializes a Swagger Path DSL block with a delete verb

Adds the description section to the operation of a swagger %PathObject{}

Initializes a Swagger Path DSL block with a get verb

Initializes a Swagger Path DSL block with a head verb

Converts the %PathObject{} struct into the nested JSON form expected by swagger

Adds the operationId section to the operation of a swagger %PathObject{}

Initializes a Swagger Path DSL block with a options verb

Adds page size, number and offset parameters to the operation of a swagger %PathObject{}

Adds a parameter to the operation of a swagger %PathObject{}

Initializes a Swagger Path DSL block with a patch verb

Initializes a Swagger Path DSL block with a post verb

Adds a mime-type to the produces list of the operation of a swagger %PathObject{}

Initializes a Swagger Path DSL block with a put verb

Adds a response to the operation of a swagger %PathObject{}, without a schema

Adds a response to the operation of a swagger %PathObject{}, with a schema

Adds the security section to the operation of a swagger %PathObject{}

Adds the summary section to the operation of a swagger %PathObject{}

Adds a tag to the operation of a swagger %PathObject{}

Macros

Defines multiple parameters for an operation with a custom DSL syntax

Functions

consumes(path, mimetype)

Adds a mime-type to the consumes list of the operation of a swagger %PathObject{}

delete(path)

Initializes a Swagger Path DSL block with a delete verb

description(path, description)

Adds the description section to the operation of a swagger %PathObject{}

expand_response_example(path_object, opts)
get(path)

Initializes a Swagger Path DSL block with a get verb

head(path)

Initializes a Swagger Path DSL block with a head verb

nest(path)

Converts the %PathObject{} struct into the nested JSON form expected by swagger

operation_id(path, id)

Adds the operationId section to the operation of a swagger %PathObject{}

options(path)

Initializes a Swagger Path DSL block with a options verb

paging(path, opts \\ [size: "page_size", number: "page"])

Adds page size, number and offset parameters to the operation of a swagger %PathObject{}

The names default to “page_size” and “page” for ease of use with scriviner_ecto, but can be overridden.

Examples

get "/api/pets/"
paging
response 200, "OK"

get "/api/pets/dogs"
paging size: "page_size", number: "count"
response 200, "OK"

get "/api/pets/cats"
paging size: "limit", offset: "offset"
response 200, "OK"
parameter(path, name, location, type, description, opts \\ [])

Adds a parameter to the operation of a swagger %PathObject{}

patch(path)

Initializes a Swagger Path DSL block with a patch verb

post(path)

Initializes a Swagger Path DSL block with a post verb

produces(path, mimetype)

Adds a mime-type to the produces list of the operation of a swagger %PathObject{}

put(path)

Initializes a Swagger Path DSL block with a put verb

response(path, status, description)

Adds a response to the operation of a swagger %PathObject{}, without a schema

response(path, status, description, schema, opts \\ [])

Adds a response to the operation of a swagger %PathObject{}, with a schema

Optional keyword args can be provided for headers and examples If the mime-type is known from the produces list, then a single can be given as a shorthand.

Example

get "/users/{id}"
produces "application/json"
parameter :id, :path, :integer, "user id", required: true
response 200, "Success", :User, examples: %{"application/json": %{id: 1, name: "Joe"}}

get "/users/{id}"
produces "application/json"
parameter :id, :path, :integer, "user id", required: true
response 200, "Success", :User, example: %{id: 1, name: "Joe"}
security(path, security)

Adds the security section to the operation of a swagger %PathObject{}

summary(path, summary)

Adds the summary section to the operation of a swagger %PathObject{}

tag(path, tag)

Adds a tag to the operation of a swagger %PathObject{}

Macros

parameters(path, block)

Defines multiple parameters for an operation with a custom DSL syntax

Example

swagger_path :create do
  post "/api/v1/{team}/users"
  summary "Create a new user"
  parameters do
    user :body, Schema.ref(:User), "user attributes"
    team :path, :string, "Users team ID"
  end
  response 200, "OK", :User
end