Phoenix Swagger

https://hexdocs.pm/phoenix_swagger/
Admin
Phoenix Swagger provides Swagger/OpenAPI integration for Phoenix web framework, including API...
Tokens:27,526
Snippets:340
Trust Score:9
Update:5 months ago
Show doc for...
Tokens:
Raw
### Define GET Operation with Response and Single Example

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.Path.html

Defines a GET operation for a user endpoint, specifying the response format and providing a single example. This is a shorthand for the `examples` keyword.

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

--------------------------------

### Index Endpoint Example

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.Path.html

Defines a GET request for fetching users with pagination and a query parameter for user ID.

```APIDOC
## GET /users

### Description
Fetches a list of users with support for pagination and filtering by user ID.

### Method
GET

### Endpoint
/users

### Parameters
#### Query Parameters
- **id** (integer) - Required - user id

#### Query Parameters (from paging)
- **page_size** (integer) - Optional - The number of items to return per page.
- **page** (integer) - Optional - The page number to retrieve.

### Response
#### Success Response (200)
- **User** (object) - User resource details.
```

--------------------------------

### example(model, example)

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.Schema.html

Adds an example value for the schema.

```APIDOC
## example(model, example)

### Description
Adds an example of the schema.

### Parameters
- `model` (Schema) - The schema object to modify.
- `example` (any) - An example value for the schema.

### Examples
```elixir
alias PhoenixSwagger.Schema

%Schema{type: :object, properties: %{name: %Schema{type: :string}}}
|> Schema.example(%{name: "Fido"})
```
```

--------------------------------

### Add an example to a schema

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.Schema.html

Use `PhoenixSwagger.Schema.example/2` to provide an example value for the schema.

```elixir
iex> alias PhoenixSwagger.Schema
...> %Schema{type: :object, properties: %{phone_number: %Schema{type: :string}}}
...> |> Schema.example(%{phone_number: "555-123-456"})
%PhoenixSwagger.Schema{
  type: :object,
  properties: %{
    phone_number: %PhoenixSwagger.Schema{
      type: :string
    }
  },
  example: %{phone_number: "555-123-456"}
}
```

--------------------------------

### Define a Swagger Path with Multiple Operations

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.Path.html

This example demonstrates how to define a complete API path with various operations like GET, specifying parameters, responses, and tags. It should be used within a `swagger_path` macro.

```elixir
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
```

--------------------------------

### Parameters DSL Example

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.Path.html

Shows how to define multiple parameters for an operation using the `parameters` block, including path and body parameters.

```APIDOC
## POST /api/v1/{team}/users

### Description
Creates a new user within a specified team.

### Method
POST

### Endpoint
/api/v1/{team}/users

### Parameters
#### Path Parameters
- **team** (string) - Required - Users team ID

#### Request Body
- **user** (object) - Required - user attributes (Schema.ref(:User))

### Response
#### Success Response (200)
- **User** (object) - The created user resource.
```

--------------------------------

### Define Swagger Path with GET Request

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.html

Defines a GET endpoint for retrieving users with query parameters and tags. This example is within a Phoenix controller context.

```elixir
defmodule ExampleController do
  use ExampleApp.Web, :controller
  use PhoenixSwagger

  swagger_path :index do
    get "/users"
    summary "Get users"
    description "Get users, filtering by account ID"
    parameter :query, :id, :integer, "account id", required: true
    response 200, "Description", :Users
    tag "users"
  end

  def index(conn, _params) do
    posts = Repo.all(Post)
    render(conn, "index.json", posts: posts)
  end
end
```

--------------------------------

### Setup and Test User Response Validation (Alternative)

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.SchemaTest.html

An alternative setup for ExUnit tests to validate a user response against a Swagger schema. This version uses `MyApp.ConnCase` and a different user ID placeholder.

```elixir
use MyApp.ConnCase
use PhoenixSwagger.SchemaTest "priv/static/swagger.json"

test "get user by ID", %{conn: conn, swagger_schema: schema} do
  response = 
    conn
    |> get(user_path(conn, :show, 123))
    |> validate_resp_schema(schema, "User")
    |> json_response(200)

  assert response["data"]["id"] == 123
end
```

--------------------------------

### Define Index Operation with PhoenixSwagger

Source: https://hexdocs.pm/phoenix_swagger/operations.html

Use the `swagger_path/2` macro to define the swagger specification for a controller's index action. This example shows a basic GET request for listing blog posts.

```elixir
use PhoenixSwagger

swagger_path :index do
  get "/posts"
  description "List blog posts"
  response 200, "Success"
end

def index(conn, _params) do
  posts = Repo.all(Post)
  render(conn, "index.json", posts: posts)
end
```

--------------------------------

### Index Endpoint

Source: https://hexdocs.pm/phoenix_swagger/json-api-helpers.html

Example of an API endpoint for listing users with pagination.

```APIDOC
## GET /api/v1/users

### Description
Retrieves a list of users with support for pagination.

### Method
GET

### Endpoint
/api/v1/users

### Query Parameters
#### Paging
- **page[size]** (string) - Optional - The number of items to return per page.
- **page[number]** (string) - Optional - The page number to retrieve.

### Response
#### Success Response (200)
- **Users** (Schema.ref(:Users)) - A JSON:API page object containing a list of user resources.
```

--------------------------------

### Configure Swagger Files

Source: https://hexdocs.pm/phoenix_swagger/Mix.Tasks.Phx.Swagger.Generate.html

Define swagger file configurations in your project's config file. This example shows how to specify the output path and the associated router and endpoint.

```elixir
config :your_app, :phoenix_swagger,
  swagger_files: %{
    "priv/static/swagger.json" => [router: YourAppWeb.Router, endpoint: YourAppWeb.Endpoint]
    # ... additional swagger files can be added here
  }
```

--------------------------------

### Define GET Operation with Response and Schema

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.Path.html

Defines a GET operation for a user endpoint, specifying the response format, schema, and providing an example with a JSON content type.

```elixir
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"}}
```

--------------------------------

### Define Multiple Parameters for an Operation

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.Path.html

This example demonstrates using the `parameters` block to define multiple parameters for an API operation using a custom DSL. It includes defining parameters for the request body, path, and query.

```elixir
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
```

--------------------------------

### Build Swagger Schema for a Pet

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.html

Builds a Swagger schema for a 'Pet' object, including properties, types, and requirements. This is an interactive example.

```elixir
iex> use PhoenixSwagger
...> swagger_schema do
...>   title "Pet"
...>   description "A pet in the pet store"
...>   properties do
...>     id :integer, "Unique identifier", required: true, format: :int64
...>     name :string, "Pets name", required: true
...>     tags array(:string), "Tag categories for this pet"
...>   end
...>   additional_properties false
...> end
```

--------------------------------

### Setup and Test User Response Validation

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.SchemaTest.html

Use this snippet to set up ExUnit tests that validate a user response against a Swagger schema. It requires the `YourApp.ConnCase` and `PhoenixSwagger.SchemaTest` modules, and assumes a `swagger.json` file is available.

```elixir
use YourApp.ConnCase
use PhoenixSwagger.SchemaTest "priv/static/swagger.json"

test "Get a user by ID", %{conn: conn, swagger_schema: schema} do
  user = Repo.insert! struct(User, @valid_attrs)
  response = 
    conn
    |> get(user_path(conn, :show, user))
    |> validate_resp_schema(schema, "UserResponse")
    |> json_response(200)

  assert response["data"]["id"] == user.id
end
```

--------------------------------

### Example of Schema Validation Error Output

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.SchemaTest.html

This example illustrates the format of errors produced when a response JSON does not conform to the specified Swagger schema. It highlights the JSON path and the specific validation failure.

```json
Response JSON does not conform to swagger schema from #/definitions/UserResponse.
At #/data/email: Expected "foobaz" to be an email address.
{
  "data": {
    "name": "Yu Ser",
    "id": 141,
    "email": "foobaz"
  }
}
```

--------------------------------

### Configure Paging Parameters for an API Path

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.Path.html

This example shows how to add default or custom paging parameters to an API operation. The default parameter names are 'page_size' and 'page', which are compatible with 'scrivener_ecto'.

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

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

```elixir
get "/api/pets/cats"
paging size: "limit", offset: "offset"
response 200, "OK"
```

--------------------------------

### List Blog Posts

Source: https://hexdocs.pm/phoenix_swagger/operations.html

Defines a GET request to list blog posts and specifies a success response.

```APIDOC
## GET /posts

### Description
List blog posts.

### Method
GET

### Endpoint
/posts

### Response
#### Success Response (200)
- Success
```

--------------------------------

### Query for Users

Source: https://hexdocs.pm/phoenix_swagger/operations.html

Defines a GET request to query users with support for paging and filtering, including path and query parameters.

```APIDOC
## GET /api/v1/{org_id}/users

### Description
Query for users. This operation supports with paging and filtering.

### Method
GET

### Endpoint
/api/v1/{org_id}/users

### Parameters
#### Path Parameters
- **org_id** (string) - Required - Organization ID

#### Query Parameters
- **zipcode** (string) - Required - Address Zip Code, example: "90210"
- **include** (array) - Optional - Related resources to include in response, items: [type: :string, enum: [:organisation, :favourites, :purchases]], collectionFormat: :csv

### Response
#### Success Response (200)
- OK - Schema.ref(:Users)

#### Error Response (400)
- Client Error
```

--------------------------------

### Index Endpoint for Users

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.JsonApi.html

Defines the GET endpoint for retrieving a list of users, including pagination support.

```APIDOC
## GET /api/v1/users

### Description
Retrieves a list of users with support for pagination.

### Method
GET

### Endpoint
/api/v1/users

### Query Parameters
- **page[size]** (string) - Number of items per page
- **page[number]** (string) - The page number to retrieve

### Response
#### Success Response (200)
- **OK**: Returns a schema conforming to the 'Users' definition, representing a collection of user resources.
```

--------------------------------

### Get Users Endpoint

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.html

Defines a GET endpoint for retrieving users, with a query parameter for filtering by account ID and a tag for grouping.

```APIDOC
## GET /users

### Description
Get users, filtering by account ID.

### Method
GET

### Endpoint
/users

### Parameters
#### Query Parameters
- **id** (integer) - Required - account id

### Response
#### Success Response (200)
- **Description** (Users)
```

--------------------------------

### Build Swagger Schema for a Phone Number

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.html

Builds a Swagger schema for a 'Phone' object, specifying it as a string with constraints on length and pattern. This is an interactive example.

```elixir
iex> use PhoenixSwagger
...> swagger_schema do
...>   title "Phone"
...>   description "An 8 digit phone number with optional 2 digit area code"
...>   type :string
...>   max_length 11
...>   pattern ~S"^(([0-9]{2}))?[0-9]{4}-[0-9]{4}$"
...> end
```

--------------------------------

### Configure Swagger File Generation

Source: https://hexdocs.pm/phoenix_swagger/swagger-ui.html

Add this configuration to your `config/config.exs` to specify the output path for the swagger file and the router to use for generation.

```elixir
config :my_app, :phoenix_swagger,
  swagger_files: %{
    "priv/static/swagger.json" => [router: MyAppWeb.Router]
  }
```

--------------------------------

### new(block)

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.Schema.html

Constructs a new %Schema{} struct using a DSL block.

```APIDOC
## new(block)

### Description
Construct a new %Schema{} struct using the schema DSL.

### Parameters
- `block` (function) - A function that defines the schema using the DSL.

### Examples
```elixir
alias PhoenixSwagger.Schema

Schema.new(fn ->
  type(:object)
  property(:id, :integer)
end)
```
```

--------------------------------

### Configure Multiple Swagger Files

Source: https://hexdocs.pm/phoenix_swagger/getting-started.html

If multiple swagger files are needed, add additional entries to the project config for each file.

```elixir
config :my_app, :phoenix_swagger,
  swagger_files: %{
    "booking-api.json" => [router: MyApp.BookingRouter],
    "reports-api.json" => [router: MyApp.ReportsRouter],
    "admin-api.json" => [router: MyApp.AdminRouter]
  }
```

--------------------------------

### Generate Swagger File

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.Plug.SwaggerUI.html

Use this mix task to generate the swagger JSON file. Place the output in your application's `priv/static` directory.

```mix
mix phoenix.swagger.generate priv/static/myapp.json
```

--------------------------------

### Generate Swagger JSON

Source: https://hexdocs.pm/phoenix_swagger/Mix.Tasks.Phx.Swagger.Generate.html

Run this task from your project's root directory to generate the swagger.json file.

```bash
mix phx.swagger.generate
```

--------------------------------

### HTTP Method Definitions

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.Path.html

Provides functions to initialize a PathObject with specific HTTP verbs.

```APIDOC
## DELETE /path

### Description
Initializes a PathObject with the HTTP verb 'delete'.

### Method
DELETE

### Endpoint
/path

## GET /path

### Description
Initializes a PathObject with the HTTP verb 'get'.

### Method
GET

### Endpoint
/path

## HEAD /path

### Description
Initializes a PathObject with the HTTP verb 'head'.

### Method
HEAD

### Endpoint
/path

## OPTIONS /path

### Description
Initializes a PathObject with the HTTP verb 'options'.

### Method
OPTIONS

### Endpoint
/path

## PATCH /path

### Description
Initializes a PathObject with the HTTP verb 'patch'.

### Method
PATCH

### Endpoint
/path

## POST /path

### Description
Initializes a PathObject with the HTTP verb 'post'.

### Method
POST

### Endpoint
/path

## PUT /path

### Description
Initializes a PathObject with the HTTP verb 'put'.

### Method
PUT

### Endpoint
/path
```

--------------------------------

### put(path_obj, path)

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.Path.html

Initializes a PathObject with the HTTP verb 'put' and the specified path.

```APIDOC
## put(path_obj, path)

### Description
Initializes a PathObject with verb "put" and given path.

### Method
PUT

### Endpoint
[Path defined by `path` argument]
```

--------------------------------

### Paging Functionality

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.Path.html

Demonstrates how to use the `paging` function to add pagination parameters to an operation.

```APIDOC
## GET /api/pets/

### Description
Fetches a list of pets with default pagination parameters.

### Method
GET

### Endpoint
/api/pets/

### Response
#### Success Response (200)
- **OK** (string) - Indicates a successful response.

## GET /api/pets/dogs

### Description
Fetches a list of dogs with custom pagination parameter names for size and count.

### Method
GET

### Endpoint
/api/pets/dogs

### Response
#### Success Response (200)
- **OK** (string) - Indicates a successful response.

## GET /api/pets/cats

### Description
Fetches a list of cats with custom pagination parameter names for limit and offset.

### Method
GET

### Endpoint
/api/pets/cats

### Response
#### Success Response (200)
- **OK** (string) - Indicates a successful response.
```

--------------------------------

### Customizing Delete Route with Qualified Call

Source: https://hexdocs.pm/phoenix_swagger/operations.html

When the `PhoenixSwagger.Path.delete/2` function might clash with a controller's own `delete/2` function, use a qualified function call to disambiguate. This example shows how to define a delete operation for a user by ID.

```elixir
  swagger_path :delete do
    PhoenixSwagger.Path.delete "/api/users/{id}"
    summary "Delete User"
    description "Delete a user by ID"
    parameter :id, :path, :integer, "User ID", required: true, example: 3
    response 203, "No Content - Deleted Successfully"
  end
```

--------------------------------

### Construct a New Schema Struct with DSL

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.Schema.html

Use this macro to build a %Schema{} struct using a custom DSL. It's similar to `swagger_schema` but produces a Schema struct directly.

```elixir
iex> require PhoenixSwagger.Schema, as: Schema
...> Schema.new do
...>   type :object
...>   properties do
...>     name :string, "user name", required: true
...>     date_of_birth :string, "date of birth", format: :datetime
...>   end
...> end
%Schema{
  type: :object,
  properties: %{
    name: %Schema {
      type: :string,
      description: "user name"
    },
    date_of_birth: %Schema {
      type: :string,
      format: :datetime,
      description: "date of birth"
    }
  },
  required: [:name]
}
```

--------------------------------

### Enable Phoenix Swagger as a Mix Compiler Task

Source: https://hexdocs.pm/phoenix_swagger/changelog.html

Integrate phoenix_swagger into the compilation process to keep generated swagger files in sync with code and enable live reloading. Ensure it's included in the list of compilers.

```elixir
compilers: [:phoenix, :gettext, :phoenix_swagger] ++ Mix.compilers
```

--------------------------------

### Reuse Common Parameters in ProjectsController

Source: https://hexdocs.pm/phoenix_swagger/reusing-swagger-parameters.html

Demonstrates reusing the common authorization and sorting parameters in the ProjectsController's Swagger definition.

```elixir
defmodule ProjectsController do
  use PhoenixSwagger

  swagger_path :index do
    get "/users"
    produces "application/json"
    CommonParameters.authorization
    CommonParameters.sorting
    parameters do
      company_id :string, :query, "The company id"
    end
  end
end
```

--------------------------------

### Detailed Operation Definition with Parameters

Source: https://hexdocs.pm/phoenix_swagger/operations.html

This snippet demonstrates a more comprehensive `swagger_path/2` definition, including summary, description, produces type, tag, operation ID, paging, complex query parameters, and multiple responses.

```elixir
swagger_path :index do
  get "/api/v1/{org_id}/users"
  summary "Query for users"
  description "Query for users. This operation supports with paging and filtering"
  produces "application/json"
  tag "Users"
  operation_id "list_users"
  paging
  parameters do
    org_id :path, :string, "Organization ID", required: true
    zipcode :query, :string, "Address Zip Code", required: true, example: "90210"
    include :query, :array, "Related resources to include in response",
              items: [type: :string, enum: [:organisation, :favourites, :purchases]],
              collectionFormat: :csv
  end
  response 200, "OK", Schema.ref(:Users)
  response 400, "Client Error"
end
```

--------------------------------

### Configure JSON Library

Source: https://hexdocs.pm/phoenix_swagger/getting-started.html

Optionally configure the JSON library to be used by phoenix_swagger.

```elixir
config :phoenix_swagger, json_library: Jason
```

--------------------------------

### Schema.new/1

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.Schema.html

Construct a new %Schema{} struct using the schema DSL. This macro is similar to PhoenixSwagger.swagger_schema, except that it produces a Schema struct instead of a plain map with string keys.

```APIDOC
## Schema.new/1

### Description
Construct a new %Schema{} struct using the schema DSL. This macro is similar to PhoenixSwagger.swagger_schema, except that it produces a Schema struct instead of a plain map with string keys.

### Method
`Schema.new(block)`

### Parameters
- `block`: A block of code defining the schema using a DSL.

### Request Example
```elixir
require PhoenixSwagger.Schema, as: Schema
Schema.new do
  type :object
  properties do
    name :string, "user name", required: true
    date_of_birth :string, "date of birth", format: :datetime
  end
end
```

### Response Example
```elixir
%Schema{
  type: :object,
  properties: %{
    name: %Schema {
      type: :string,
      description: "user name"
    },
    date_of_birth: %Schema {
      type: :string,
      format: :datetime,
      description: "date of birth"
    }
  },
  required: [:name]
}
```
```

--------------------------------

### Create User Endpoint

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.html

Defines a POST endpoint for creating a new user, including request parameters and response schema.

```APIDOC
## POST /api/v1/{team}/users

### Description
Create a new user.

### Method
POST

### Endpoint
/api/v1/{team}/users

### Parameters
#### Path Parameters
- **team** (string) - Required - Users team ID

#### Request Body
- **user** (Schema.ref(:User)) - Required - user attributes

### Response
#### Success Response (200)
- **OK** (Schema.ref(:User))
```

--------------------------------

### Create Schema Reference

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.Schema.html

Use the `ref` function to create a schema reference. This can be a named definition within the swagger document or a complete path.

```elixir
PhoenixSwagger.Schema.ref(:User)
```

```elixir
PhoenixSwagger.Schema.ref("../common/Error.json")
```

--------------------------------

### Configure Swagger File Output

Source: https://hexdocs.pm/phoenix_swagger/getting-started.html

Add a config entry to specify the output filename, router, and endpoint modules for swagger file generation.

```elixir
config :my_app, :phoenix_swagger,
  swagger_files: %{
    "priv/static/swagger.json" => [
      router: MyAppWeb.Router,     # phoenix routes will be converted to swagger paths
      endpoint: MyAppWeb.Endpoint  # (optional) endpoint config used to set host, port and https schemes.
    ]
  }
```

--------------------------------

### Define Swagger Path and Schema

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.html

Defines a POST endpoint for creating a user and a schema for the User object. Ensure PhoenixSwagger is used.

```elixir
use PhoenixSwagger

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

def swagger_definitions do
  %{ 
    User: swagger_schema do
      title "User"
      description "A user of the application"
      properties do
        name :string, "Users name", required: true
        id :string, "Unique identifier", required: true
        address :string, "Home adress"
      end
    end
  }
end
```

--------------------------------

### Define Project Index Swagger Path

Source: https://hexdocs.pm/phoenix_swagger/reusing-swagger-parameters.html

Defines the Swagger path for the 'index' action in ProjectsController, including common parameters.

```elixir
defmodule ProjectsController do
  use PhoenixSwagger

  swagger_path :index do
    get "/projects"
    produces "application/json"
    parameter("Authorization", :header, :string, "OAuth2 access token", required: true)
    parameters do      
      sort_by :query, :string, "The property to sort by"
      sort_direction :query, :string, "The sort direction", enum: [:asc, :desc], default: :asc
      company_id :string, :query, "The company id"
    end
  end
end
```

--------------------------------

### Single Object

Source: https://hexdocs.pm/phoenix_swagger/json-api-helpers.html

Wraps a resource definition into a JSON:API single object.

```APIDOC
## JsonApi.single/1

### Description
Wraps a resource in a JSON:API top level object for a single resource.

### Usage
```elixir
JsonApi.single(:ResourceName)
```
```

--------------------------------

### Configure Phoenix Swagger Compiler

Source: https://hexdocs.pm/phoenix_swagger/getting-started.html

Append :phoenix_swagger to the compilers list in your project's mix.exs to automatically update swagger files on compilation.

```elixir
def project do
[
  ...,
  compilers: [:phoenix, :gettext] ++ Mix.compilers ++ [:phoenix_swagger],
  ...
]
```

--------------------------------

### format(model, format)

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.Schema.html

Sets the format for a string type schema.

```APIDOC
## format(model, format)

### Description
Sets the format of a Schema with `type: :string`.

### Parameters
- `model` (Schema) - The schema object to modify.
- `format` (string) - The format string (e.g., "date-time", "email", "uuid").

### Examples
```elixir
alias PhoenixSwagger.Schema

%Schema{type: :string}
|> Schema.format("date-time")
```
```

--------------------------------

### Create CommonParameters Module

Source: https://hexdocs.pm/phoenix_swagger/reusing-swagger-parameters.html

Defines a module to hold reusable Swagger parameter definitions for authorization and sorting.

```elixir
defmodule CommonParameters do
  @moduledoc "Common parameter declarations for phoenix swagger"

  alias PhoenixSwagger.Path.PathObject
  import PhoenixSwagger.Path

  def authorization(path = %PathObject{}) do
    path |> parameter("Authorization", :header, :string, "OAuth2 access token", required: true)
  end

  def sorting(path = %PathObject{}) do
    path
    |> parameter(:sort_by, :query, :string, "The property to sort by")
    |> parameter(:sort_direction, :query, :string, "The sort direction", enum: [:asc, :desc], default: :asc)
  end
end
```

--------------------------------

### Set a description for a schema

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.Schema.html

Use `PhoenixSwagger.Schema.description/2` to add a descriptive string to a schema.

```elixir
iex> alias PhoenixSwagger.Schema
...> %Schema{} |> Schema.description("A user")
%PhoenixSwagger.Schema{description: "A user"}
```

--------------------------------

### Configure Live Reloading for Phoenix Swagger

Source: https://hexdocs.pm/phoenix_swagger/live-reloading.html

Add `phoenix_swagger` as a compiler and configure the `live_reload` patterns and `reloadable_compilers` in your endpoint configuration. This enables automatic regeneration and reloading of swagger files when controller or view files change.

```elixir
config :your_app, YourApp.Endpoint,
  live_reload: [
    patterns: [
      ~r{priv/static/.*(js|css|png|jpeg|jpg|gif|svg|json)$},
      ~r{priv/gettext/.*(po)$},
      ~r{lib/your_app_web/views/.*(ex)$},
      ~r{lib/your_app_web/controllers/.*(ex)$},
      ~r{lib/your_app_web/templates/.*(eex)$}
    ]
  ],
  reloadable_compilers: [:gettext, :phoenix, :elixir, :phoenix_swagger]
```

--------------------------------

### Define Swagger Schema Definitions

Source: https://hexdocs.pm/phoenix_swagger/schemas.html

Use the `swagger_definitions/0` function in your controller module to return a map of schema definitions. The `swagger_schema/2` macro helps build these definitions.

```elixir
def swagger_definitions do
  %{ 
    User: swagger_schema do
      title "User"
      description "A user of the application"
      properties do
        name :string, "Users name", required: true
        id :string, "Unique identifier", required: true
        address :string, "Home address"
        preferences (Schema.new do
          properties do
            subscribe_to_mailing_list :boolean, "mailing list subscription", default: true
            send_special_offers :boolean, "special offers list subscription", default: true
          end
        end)
      end
      example %{
        name: "Joe",
        id: "123",
        address: "742 Evergreen Terrace"
      }
    end,
    Users: swagger_schema do
      title "Users"
      description "A collection of Users"
      type :array
      items Schema.ref(:User)
    end
  }
end
```

--------------------------------

### Schema.properties/2

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.Schema.html

Defines multiple properties for a schema with a custom DSL syntax.

```APIDOC
## Schema.properties/2

### Description
Defines multiple properties for a schema with a custom DSL syntax.

### Method
`Schema.properties(model, block)`

### Parameters
- `model`: The schema struct to modify.
- `block`: A block of code defining the properties.

### Request Example
```elixir
# This function is typically used within Schema.new/1
alias PhoenixSwagger.Schema
Schema.new do
  type :object
  properties do
    id :integer, "unique identifier"
    name :string, "user name"
  end
end
```

### Response Example
```elixir
# Example response structure after using properties within Schema.new/1
%Schema{
  type: :object,
  properties: %{
    id: %Schema{type: :integer, description: "unique identifier"},
    name: %Schema{type: :string, description: "user name"}
  }
}
```
```

--------------------------------

### Configure Router for Swagger UI

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.Plug.SwaggerUI.html

Add this scope to your Phoenix router to forward requests to the SwaggerUI plug. Ensure `otp_app` and `swagger_file` options match your configuration.

```elixir
scope "myapp/api/swagger" do
  forward "/", PhoenixSwagger.Plug.SwaggerUI, otp_app: :myapp, swagger_file: "myapp.json"
end
```

--------------------------------

### all_of(model, schemas)

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.Schema.html

Combines multiple schemas, requiring a value to conform to all of them. Useful for defining inheritance or composition.

```APIDOC
## all_of(model, schemas)

### Description
Used to combine multiple schemas, requiring a value to conform to all schemas. Can be used in conjunction with `discriminator` to define polymorphic inheritance relationships.

### Parameters
- `model` (Schema) - The schema object to modify.
- `schemas` (list of Schema) - A list of schemas to combine.

### Examples
```elixir
alias PhoenixSwagger.Schema

%Schema{}
|> Schema.all_of([Schema.ref("#definitions/Contact"), Schema.ref("#definitions/CreditHistory")])
```
```

--------------------------------

### Combine Schemas with all_of

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.Schema.html

Use `all_of` to create a schema that must conform to all provided sub-schemas. This is useful for composition and defining polymorphic relationships.

```elixir
iex> alias PhoenixSwagger.Schema
...> %Schema{}
...> |> Schema.all_of([Schema.ref("#definitions/Contact"), Schema.ref("#definitions/CreditHistory")])
%PhoenixSwagger.Schema{
  allOf: [
    %PhoenixSwagger.Schema{"$ref": "#definitions/Contact"},
    %PhoenixSwagger.Schema{"$ref": "#definitions/CreditHistory"},
  ]
```

--------------------------------

### property(model, name, type_or_schema, description \\ nil, opts \\ [])

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.Schema.html

Sets a single property for an object schema, defining its name, type, description, and options.

```APIDOC
## property(model, name, type_or_schema, description \\ nil, opts \\ [])

### Description
Sets a property of the Schema.

### Parameters
- `model` (Schema) - The schema object to modify.
- `name` (string) - The name of the property.
- `type_or_schema` (atom | Schema) - The type or schema definition for the property.
- `description` (string, optional) - A description for the property.
- `opts` (keyword list, optional) - Additional options for the property (e.g., `maxLength`, `required`).

### Examples
```elixir
alias PhoenixSwagger.Schema

%Schema{type: :object}
|> Schema.property(:username, :string, "The user's unique identifier", required: true, maxLength: 50)
```
```

--------------------------------

### Add Phoenix Swagger Dependency

Source: https://hexdocs.pm/phoenix_swagger/getting-started.html

Add the phoenix_swagger dependency to your mix.exs file. ex_json_schema is optional and only needed for schema validation.

```elixir
def deps do
  [
    {:phoenix_swagger, "~> 0.8"},
    {:ex_json_schema, "~> 0.5"} # optional
  ]
end
```

--------------------------------

### properties(model, block)

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.Schema.html

Defines multiple properties for an object schema using a custom DSL syntax.

```APIDOC
## properties(model, block)

### Description
Defines multiple properties for a schema with a custom DSL syntax.

### Parameters
- `model` (Schema) - The schema object to modify.
- `block` (function) - A function that defines properties using the DSL.

### Examples
```elixir
alias PhoenixSwagger.Schema

%Schema{type: :object}
|> Schema.properties(fn ->
  property(:name, :string, "User's name")
  property(:age, :integer, "User's age")
end)
```
```

--------------------------------

### description(model, desc)

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.Schema.html

Sets the description for a schema.

```APIDOC
## description(model, desc)

### Description
Sets the description for the schema.

### Parameters
- `model` (Schema) - The schema object to modify.
- `desc` (string) - The description for the schema.

### Examples
```elixir
alias PhoenixSwagger.Schema

%Schema{type: :string}
|> Schema.description("User's full name")
```
```

--------------------------------

### Define Swagger Definitions with JsonApi DSL

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.JsonApi.html

Use this DSL to define resources, pages, and single resource schemas for your API. It includes attributes, links, and relationships.

```elixir
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
```

--------------------------------

### PhoenixSwagger.Plug.Validate

Source: https://hexdocs.pm/phoenix_swagger/schema-validation.html

A default Plug to automatically validate input parameters for controllers.

```APIDOC
## Default Plug: PhoenixSwagger.Plug.Validate

### Description
Integrates validation directly into the request pipeline using a Plug.

### Method
`plug PhoenixSwagger.Plug.Validate`

### Usage
Add `PhoenixSwagger.Plug.Validate` to your pipeline in the router.

```elixir
pipeline :api do
  plug :accepts, ["json"]
  plug PhoenixSwagger.Plug.Validate
end

scope "/api", MyApp do
  pipe_through :api
  post "/users", UsersController, :send
end
```

### Response on Error
On validation errors, this Plug returns a `400` status code with a JSON body:

```json
{
  "error": {
    "path": "#/path/to/schema",
    "message": "Expected integer, got null"
  }
}
```

### Configuration
The return status code for validation errors can be configured via the `:validation_failed_status` parameter. Validation can be skipped if `conn.private[:phoenix_swagger][:valid]` is set to `true`.
```

--------------------------------

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

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.Path.html

Adds a response to the operation of a swagger PathObject with an optional schema and other options.

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

### Description
Adds a response to the operation of a swagger `%PathObject{}`, with a schema. Optional keyword args can be provided for `headers` and `examples`.

### Parameters
#### Path Parameters
- **path**: The PathObject to add the response to.
- **status** (integer) - Required - The HTTP status code for the response.
- **description** (string) - Required - A description of the response.
- **schema** (any) - Required - The schema for the response.
- **opts** (keyword list) - Optional - Keyword arguments for `headers` and `examples`.
```

--------------------------------

### Optional Swagger Info Fields

Source: https://hexdocs.pm/phoenix_swagger/getting-started.html

You can include optional fields like `basePath` and `tags` in the `swagger_info/0` function for more detailed API descriptions.

```elixir
%{
  basePath: "/api",
  info: %{..},
  tags: [%{name: "Users", description: "Operations about Users"}]
}
```

--------------------------------

### array(name)

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.Schema.html

Constructs an array schema where the items are defined by a reference to another schema.

```APIDOC
## array(name)

### Description
Construct an array schema, where the array items schema is a ref to the given name.

### Parameters
- `name` (string) - The name of the schema definition to reference for array items.

### Examples
```elixir
alias PhoenixSwagger.Schema

Schema.array("#definitions/User")
```
```

--------------------------------

### Resource Definition

Source: https://hexdocs.pm/phoenix_swagger/json-api-helpers.html

Defines a JSON:API resource object with attributes, links, and relationships.

```APIDOC
## JsonApi.resource/1

### Description
Describes a JSON:API resource object.

### Usage
```elixir
JsonApi.resource do
  description "A description of the resource."
  attributes do
    field_name :type, "Description of the field"
    field_name :type, "Description", format: "format_string"
    field_name :type, "Description", required: true
  end
  link :link_name, "Link description"
  relationship :relationship_name
  relationship :relationship_name, type: :has_many
end
```
```

--------------------------------

### Alternative Sorting Parameter Definition

Source: https://hexdocs.pm/phoenix_swagger/reusing-swagger-parameters.html

An alternative way to define sorting parameters using the 'parameters' macro within a function.

```elixir
def sorting(path = %PathObject{}) do
  parameters path do
    sort_by :query, :string, "The property to sort by"
    sort_direction :query, :string, "The sort direction", enum: [:asc, :desc], default: :asc
  end
end
```

--------------------------------

### Define Object Properties with Schema

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.Schema.html

Use the `properties` function to define properties for an object schema, including types, descriptions, and required fields.

```elixir
alias PhoenixSwagger.Schema
%> %Schema{type: :object}
%> Schema.properties do
     name :string, "Full Name", required: true
     dateOfBirth :string, "Date of birth", format: :datetime
   end
```

--------------------------------

### Define JSON:API Resource Schema

Source: https://hexdocs.pm/phoenix_swagger/json-api-helpers.html

Use `JsonApi.resource/1` to define a JSON:API resource schema with attributes, links, and relationships. Specify required fields and references to other schemas.

```elixir
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 :preferences
      relationship :posts, type: :has_many
    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
```

--------------------------------

### User Resource Definition

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.JsonApi.html

Defines a 'UserResource' according to JSON-API specifications, including attributes, links, and relationships.

```APIDOC
## UserResource Definition

### Description
Defines a JSON-API resource for a user, including their attributes, self link, and a relationship to posts.

### Attributes
- **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
- **birthday** (string) - Birthday in YYYY-MM-DD format
- **address** (Schema.ref(:Address)) - Users address

### Links
- **self**: The link to this user resource

### Relationships
- **posts**: Relationship to posts
```

--------------------------------

### Page Object

Source: https://hexdocs.pm/phoenix_swagger/json-api-helpers.html

Wraps a resource definition into a JSON:API page object.

```APIDOC
## JsonApi.page/1

### Description
Wraps a resource in a JSON:API top level object for a collection.

### Usage
```elixir
JsonApi.page(:ResourceName)
```
```

--------------------------------

### Construct Array Schema with Item Reference

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.Schema.html

Use the `array` function to define an array schema where the items are referenced by a given name.

```elixir
iex> alias PhoenixSwagger.Schema
...> Schema.array(:string)
%PhoenixSwagger.Schema{
  type: :array,
  items: %PhoenixSwagger.Schema{
    type: :string
  }
}
```

--------------------------------

### Set Schema Title

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.Schema.html

Use the `title` function to set the title for a schema object.

```elixir
alias PhoenixSwagger.Schema
%> %Schema{} |> Schema.title("User")
```

--------------------------------

### response(path, status, description)

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.Path.html

Adds a response to the operation of a swagger PathObject without a schema.

```APIDOC
## response(path, status, description)

### Description
Adds a response to the operation of a swagger `%PathObject{}`, without a schema.

### Parameters
#### Path Parameters
- **path**: The PathObject to add the response to.
- **status** (integer) - Required - The HTTP status code for the response.
- **description** (string) - Required - A description of the response.
```

--------------------------------

### summary(path, summary)

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.Path.html

Adds the summary section to the operation of a swagger PathObject.

```APIDOC
## summary(path, summary)

### Description
Adds the summary section to the operation of a swagger `%PathObject{}`.

### Parameters
#### Path Parameters
- **path**: The PathObject to add the summary to.
- **summary** (string) - Required - The summary text.
```

--------------------------------

### title(model, title)

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.Schema.html

Sets the title for a schema.

```APIDOC
## title(model, title)

### Description
Sets the title of the schema.

### Parameters
- `model` (Schema) - The schema object to modify.
- `title` (string) - The title for the schema.

### Examples
```elixir
alias PhoenixSwagger.Schema

%Schema{type: :object}
|> Schema.title("User Object")
```
```

--------------------------------

### Infer HTTP Verb and Path from Phoenix Router

Source: https://hexdocs.pm/phoenix_swagger/changelog.html

Allows HTTP verbs and paths to be inferred directly from the Phoenix router configuration, simplifying swagger path definitions. This is an alternative to explicitly defining them.

```elixir
swagger_path :show do
  get "/api/users/{id}"
  description "Gets a user by ID"
  response 200, "OK", Schema.ref(User)
end
```

```elixir
swagger_path :show do
  description "Gets a user by ID"
  response 200, "OK", Schema.ref(User)
end
```

--------------------------------

### Integrate PhoenixSwagger.Plug.Validate into Router

Source: https://hexdocs.pm/phoenix_swagger/schema-validation.html

Add this Plug to your Phoenix router pipeline to automatically validate incoming request parameters against the loaded Swagger schema. Validation errors result in a `400` response by default.

```elixir
pipeline :api do
  plug :accepts, ["json"]
  plug PhoenixSwagger.Plug.Validate
end

scope "/api", MyApp do
  pipe_through :api
  post "/users", UsersController, :send
end
```

--------------------------------

### Add Swagger UI Scope to Router

Source: https://hexdocs.pm/phoenix_swagger/swagger-ui.html

Include this scope in your Phoenix router to forward requests to the Swagger UI plug. Ensure the `swagger_file` parameter matches the one configured for generation.

```elixir
scope "/api/swagger" do
  forward "/", PhoenixSwagger.Plug.SwaggerUI, otp_app: :myapp, swagger_file: "swagger.json"
end
```

--------------------------------

### default(model, default)

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.Schema.html

Sets the default value for a schema.

```APIDOC
## default(model, default)

### Description
Sets the default value for the schema.

### Parameters
- `model` (Schema) - The schema object to modify.
- `default` (any) - The default value for the schema.

### Examples
```elixir
alias PhoenixSwagger.Schema

%Schema{type: :string}
|> Schema.default("John Doe")
```
```

--------------------------------

### Schema.min_properties/2

Source: https://hexdocs.pm/phoenix_swagger/PhoenixSwagger.Schema.html

Limits the minimum number of properties an `object` schema may contain.

```APIDOC
## Schema.min_properties/2

### Description
Limits the minimum number of properties an `object` schema may contain.

### Method
`Schema.min_properties(model, value)`

### Parameters
- `model`: The schema struct to modify.
- `value`: The minimum number of properties.

### Request Example
```elixir
alias PhoenixSwagger.Schema
%Schema{type: :object} |> Schema.min_properties(1)
```

### Response Example
```elixir
%PhoenixSwagger.Schema{type: :object, minProperties: 1}
```
```

--------------------------------

### Configure Phoenix Swagger in Application Config

Source: https://hexdocs.pm/phoenix_swagger/changelog.html

Specify swagger files, router, and endpoint modules within the application configuration. This replaces passing module names and output paths as mix task parameters.

```elixir
config :my_app, :phoenix_swagger,
  swagger_files: %{
    "priv/static/swagger.json" => [router: MyAppWeb.Router, endpoint: MyAppWeb.Endpoint]
    # additional swagger files here
  }
```
Tokens:
Raw