PhoenixSwagger.Path (phoenix_swagger v0.8.3) View Source

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

Link to this section Summary

Functions

consumes(path, mimetype)

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

delete(path_obj, path)

Initializes a PathObject with verb "delete" and given path

deprecated(path, status)

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

description(path, description)

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

expand_response_example(path_object, opts)

get(path_obj, path)

Initializes a PathObject with verb "get" and given path

head(path_obj, path)

Initializes a PathObject with verb "head" and given 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_obj, path)

Initializes a PathObject with verb "options" and given path

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

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

parameter(path, name, location, type, description, opts \\ [])

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

parameters(path, block)

Defines multiple parameters for an operation with a custom DSL syntax

patch(path_obj, path)

Initializes a PathObject with verb "patch" and given path

post(path_obj, path)

Initializes a PathObject with verb "post" and given path

produces(path, mimetype)

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

put(path_obj, path)

Initializes a PathObject with verb "put" and given path

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

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{}

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

Link to this section Functions

consumes(path, mimetype)

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

delete(path_obj, path)

Initializes a PathObject with verb "delete" and given path

deprecated(path, status)

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

description(path, description)

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

expand_response_example(path_object, opts)

get(path_obj, path)

Initializes a PathObject with verb "get" and given path

head(path_obj, path)

Initializes a PathObject with verb "head" and given path

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_obj, path)

Initializes a PathObject with verb "options" and given path

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{}

parameters(path, block)

(macro)

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

patch(path_obj, path)

Initializes a PathObject with verb "patch" and given path

post(path_obj, path)

Initializes a PathObject with verb "post" and given path

produces(path, mimetype)

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

put(path_obj, path)

Initializes a PathObject with verb "put" and given path

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{}