Phoenix Swagger

https://github.com/xerions/phoenix_swagger
Admin
Phoenix Swagger is a library that provides Swagger/OpenAPI integration to the Phoenix web framework,...
Tokens:20,513
Snippets:102
Trust Score:5.6
License:MPL-2.0
Update:7 months ago
Show doc for...
Tokens:
Raw
### GET /api/products

Source: https://context7.com/xerions/phoenix_swagger/llms.txt

Retrieves a list of products with support for pagination, sorting, and filtering.

```APIDOC
## GET /api/products

### Description
Retrieves a list of products with support for pagination, sorting, and filtering.

### Method
GET

### Endpoint
/api/products

### Parameters
#### Query Parameters
- **Authorization** (string) - Required - Bearer token
- **page** (integer) - Optional - Page number (minimum: 1, default: 1)
- **page_size** (integer) - Optional - Items per page (minimum: 1, maximum: 100, default: 20)
- **sort_by** (string) - Optional - Field to sort by
- **sort_dir** (string) - Optional - Sort direction (enum: [asc, desc], default: asc)
- **category** (string) - Optional - Filter by category
- **min_price** (number) - Optional - Minimum price
- **max_price** (number) - Optional - Maximum price

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

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

### GET /posts

Source: https://github.com/xerions/phoenix_swagger/blob/master/guides/operations.md

This endpoint lists blog posts. It uses the `swagger_path` macro to define the GET request for '/posts' and specifies a 200 OK response.

```APIDOC
## GET /posts

### Description
List blog posts.

### Method
GET

### Endpoint
/posts

### Parameters
#### Query Parameters
(No query parameters defined)

#### Request Body
(No request body defined)

### Request Example
(No request example provided)

### Response
#### Success Response (200)
- **Success** (string) - Indicates a successful listing of blog posts.

#### Response Example
(No response example provided)
```

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

### Install PhoenixSwagger Dependency

Source: https://github.com/xerions/phoenix_swagger/blob/master/guides/getting-started.md

Add PhoenixSwagger and its optional dependency ex_json_schema to your project's mix.exs file. ex_json_schema is required for schema validation and test helpers.

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

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

### Install and Configure Phoenix Swagger (Elixir)

Source: https://context7.com/xerions/phoenix_swagger/llms.txt

This snippet shows how to add phoenix_swagger and ex_json_schema to your project's dependencies in `mix.exs` and configure the swagger file output and JSON library in `config.exs`. The `ex_json_schema` is optional and used for schema validation.

```elixir
# mix.exs
def deps do
  [
    {:phoenix_swagger, "~> 0.8"},
    {:ex_json_schema, "~> 0.5"} # optional, for schema validation
  ]
end

def project do
  [
    # ... other config
    compilers: [:phoenix, :gettext] ++ Mix.compilers() ++ [:phoenix_swagger]
  ]
end

# config/config.exs
config :my_app, :phoenix_swagger,
  swagger_files: %{
    "priv/static/swagger.json" => [
      router: MyAppWeb.Router,
      endpoint: MyAppWeb.Endpoint
    ]
  }

# Configure JSON library (optional, defaults to Poison)
config :phoenix_swagger, json_library: Jason
```

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

### GET /projects

Source: https://github.com/xerions/phoenix_swagger/blob/master/guides/reusing-swagger-parameters.md

This endpoint retrieves a list of projects and supports sorting by specified parameters. It requires an Authorization header.

```APIDOC
## GET /projects

### Description
Retrieves a list of projects, allowing sorting by specified criteria and requiring an Authorization header.

### Method
GET

### Endpoint
/projects

### Parameters
#### Path Parameters
None

#### Query Parameters
- **sort_by** (string) - Optional - The property to sort by
- **sort_direction** (string) - Optional - The sort direction, enum: [:asc, :desc], default: :asc
- **company_id** (string) - Optional - The company id

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **(object)** - Description of the response body structure (e.g., array of project objects)

#### Response Example
```json
{
  "projects": [
    {
      "id": "123",
      "name": "Project Alpha"
    }
  ]
}
```
```

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

### Document API Operations with swagger_path

Source: https://context7.com/xerions/phoenix_swagger/llms.txt

This snippet illustrates how to document API operations directly within Elixir controller actions using the `swagger_path` macro. It covers defining HTTP methods, paths, summaries, descriptions, request parameters (path, query, body), responses with schemas and examples, and tags for organizing operations.

```elixir
defmodule MyAppWeb.UserController do
  use MyAppWeb, :controller
  use PhoenixSwagger

  swagger_path :index do
    get "/api/users"
    summary "List Users"
    description "Retrieve a paginated list of all users"
    produces "application/json"
    tag "Users"
    operation_id "list_users"
    paging size: "page_size", number: "page"
    parameter :filter, :query, :string, "Filter users by name", required: false
    response 200, "OK", Schema.ref(:UsersResponse),
      example: %{
        data: [
          %{id: 1, name: "Alice", email: "alice@example.com"},
          %{id: 2, name: "Bob", email: "bob@example.com"}
        ]
      }
    response 401, "Unauthorized"
  end

  def index(conn, params) do
    users = Accounts.list_users(params)
    render(conn, "index.json", users: users)
  end

  swagger_path :show do
    get "/api/users/{id}"
    summary "Get User"
    description "Retrieve a user by ID"
    produces "application/json"
    tag "Users"
    parameter :id, :path, :integer, "User ID", required: true, example: 123
    response 200, "OK", Schema.ref(:UserResponse),
      example: %{data: %{id: 123, name: "John", email: "john@example.com"}}
    response 404, "User not found", Schema.ref(:ErrorResponse)
  end

  def show(conn, %{"id" => id}) do
    user = Accounts.get_user!(id)
    render(conn, "show.json", user: user)
  end

  swagger_path :create do
    post "/api/users"
    summary "Create User"
    description "Create a new user account"
    consumes "application/json"
    produces "application/json"
    tag "Users"
    parameter :user, :body, Schema.ref(:UserRequest), "User attributes",
      example: %{user: %{name: "Jane", email: "jane@example.com"}}
    response 201, "Created", Schema.ref(:UserResponse)
    response 422, "Validation errors", Schema.ref(:ErrorResponse)
  end

  def create(conn, %{"user" => user_params}) do
    with {:ok, user} <- Accounts.create_user(user_params) do
      conn
      |> put_status(:created)
      |> put_resp_header("location", Routes.user_path(conn, :show, user))
      |> render("show.json", user: user)
    end
  end

  swagger_path :update do
    put "/api/users/{id}"
    summary "Update User"
    description "Update an existing user"
    consumes "application/json"
    produces "application/json"
    tag "Users"
    parameters do
      id :path, :integer, "User ID", required: true, example: 123
      user :body, Schema.ref(:UserRequest), "User attributes"
    end
    response 200, "Updated", Schema.ref(:UserResponse)
    response 404, "Not found"
    response 422, "Validation errors"
  end

  swagger_path :delete do
    PhoenixSwagger.Path.delete "/api/users/{id}"
    summary "Delete User"
    description "Delete a user by ID"
    tag "Users"
    parameter :id, :path, :integer, "User ID", required: true, example: 123
    response 204, "No Content"
    response 404, "Not found"
  end
end
```

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

### Generate Swagger Documentation with Edeliver Hook

Source: https://github.com/xerions/phoenix_swagger/wiki/edeliver-hook

This bash script defines a function `swagger_documentation` that is intended to be used as an Edeliver hook. It generates Swagger documentation for a Phoenix application by running `mix phoenix.swagger.generate` and then copies the resulting `swagger.json` file to the `priv/static` directory. It includes error handling and environment variable setup.

```bash
swagger_documentation() {
  status "Generating swagger documentation"

  __sync_remote "
    # runs the commands on the build host
    [ -f ~/.profile ] && source ~/.profile # load profile (optional)

    # fail if any command fails (recommended)
    set -e

    # enter the build directory on the build host (required)
    cd '$BUILD_AT'

    # run phoenix.swagger.generate
    APP='$APP' MIX_ENV='$TARGET_MIX_ENV' $MIX_CMD phoenix.swagger.generate $SILENCE

    # copy swagger.json to priv/static
    cp '$BUILD_AT/swagger.json' '$BUILD_AT/priv/static/'
  "
}

post_erlang_clean_compile() {
  swagger_documentation

  # phoenix digest code in case you want to generate it.
}
```

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

### GET /api/users

Source: https://context7.com/xerions/phoenix_swagger/llms.txt

Retrieve a paginated list of all users.

```APIDOC
## GET /api/users

### Description
Retrieve a paginated list of all users.

### Method
GET

### Endpoint
/api/users

### Query Parameters
- **page_size** (string) - Optional - Page size for pagination
- **page** (string) - Optional - Page number for pagination
- **filter** (string) - Optional - Filter users by name

### Response
#### Success Response (200)
- **data** (array of objects) - List of users. Example: `[{id: 1, name: "Alice", email: "alice@example.com"}, {id: 2, name: "Bob", email: "bob@example.com"}]`

#### Error Response (401)
Unauthorized
```

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

### Configure Swagger Files in Phoenix

Source: https://github.com/xerions/phoenix_swagger/blob/master/guides/swagger-ui.md

This configuration snippet shows how to specify swagger files and their corresponding routers within a Phoenix application's configuration. It requires the `phoenix_swagger` library to be installed and configured.

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

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

### Define Schema Properties with Required Fields (Elixir)

Source: https://github.com/xerions/phoenix_swagger/blob/master/guides/test-helpers.md

Example of defining schema properties in Elixir, specifying data types, descriptions, and marking fields as required. This is a prerequisite for using the SchemaTest helper effectively.

```elixir
properties do
  id(:integer, "User ID")
  name(:string, "User name", required: true)
  email(:string, "Email address", format: :email, required: true)
  inserted_at(:string, "Creation timestamp", format: :datetime)
  updated_at(:string, "Update timestamp", format: :datetime)
end
```

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

### Initial Swagger Path Definition in Elixir

Source: https://github.com/xerions/phoenix_swagger/blob/master/guides/reusing-swagger-parameters.md

This Elixir code snippet shows an initial definition of a Swagger path for an index action in a `ProjectsController`. It includes GET request details, produces type, and defines specific parameters and headers.

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

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

### GET /books

Source: https://github.com/xerions/phoenix_swagger/blob/master/guides/reusing-swagger-parameters.md

This endpoint retrieves a list of books and supports sorting by specified parameters. It requires an Authorization header.

```APIDOC
## GET /books

### Description
Retrieves a list of books, allowing sorting by specified criteria and requiring an Authorization header.

### Method
GET

### Endpoint
/books

### Parameters
#### Path Parameters
None

#### Query Parameters
- **sort_by** (string) - Optional - The property to sort by
- **sort_direction** (string) - Optional - The sort direction, enum: [:asc, :desc], default: :asc

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **(object)** - Description of the response body structure (e.g., array of book objects)

#### Response Example
```json
{
  "books": [
    {
      "id": "456",
      "title": "The Great Novel"
    }
  ]
}
```
```

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

### GET /api/v1/users

Source: https://github.com/xerions/phoenix_swagger/blob/master/guides/json-api-helpers.md

Retrieves a paginated list of users.

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

### Description
Retrieves a paginated list of users.

### Method
GET

### Endpoint
/api/v1/users

### Parameters
#### Path Parameters
None

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

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **data** (array) - An array of user resources.

#### Response Example
```json
{
  "data": [
    {
      "type": "UserResource",
      "id": "user-1",
      "attributes": {
        "phone": "111-222-3333",
        "full_name": "Alice Smith",
        "user_updated_at": "2023-10-27T11:00:00Z",
        "user_created_at": "2023-01-02T10:00:00Z",
        "email": "alice.smith@example.com",
        "birthday": "1992-08-20",
        "address": {
          "street": "456 Oak Ave",
          "city": "Otherville"
        }
      },
      "links": {
        "self": "/api/v1/users/user-1"
      },
      "relationships": {
        "preferences": {
          "data": {
            "type": "PreferencesResource",
            "id": "user-prefs-id-alice"
          }
        },
        "posts": {
          "data": []
        }
      }
    }
    // ... more user objects
  ],
  "links": {
    "self": "/api/v1/users?page[size]=10&page[number]=1",
    "next": "/api/v1/users?page[size]=10&page[number]=2"
  }
}
```
```

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

### Get Swagger UI Asset Path (Node.js)

Source: https://github.com/xerions/phoenix_swagger/blob/master/priv/static/README.md

Shows how to use the `getAbsoluteFSPath` method exported by the `swagger-ui-dist` module to obtain the absolute file system path to the Swagger UI assets. This path can then be used by a server to serve these static files.

```javascript
const swaggerUiAssetPath = require("swagger-ui-dist").getAbsoluteFSPath()

// then instantiate server that serves files from the swaggerUiAssetPath
```

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

### GET /api/users/{id}

Source: https://context7.com/xerions/phoenix_swagger/llms.txt

Retrieve a user by ID.

```APIDOC
## GET /api/users/{id}

### Description
Retrieve a user by ID.

### Method
GET

### Endpoint
/api/users/{id}

### Path Parameters
- **id** (integer) - Required - User ID. Example: `123`

### Response
#### Success Response (200)
- **data** (object) - The user details. Example: `{"data": {"id": 123, "name": "John", "email": "john@example.com"}}`

#### Error Response (404)
User not found. Schema: `ErrorResponse`
```

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

### Define Swagger Schemas with Phoenix Swagger

Source: https://github.com/xerions/phoenix_swagger/blob/master/guides/schemas.md

This Elixir code snippet demonstrates how to define Swagger schema objects for an application using the `swagger_schema/2` macro. It specifies the structure, types, descriptions, and examples for 'User' and 'Users' schemas. This is typically placed within a controller module's `swagger_definitions/0` function.

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

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

### Validate Request Parameters with Validator.validate/2

Source: https://github.com/xerions/phoenix_swagger/blob/master/guides/schema-validation.md

Demonstrates how to use the `Validator.validate/2` function to check if request parameters conform to the loaded swagger schema. It shows examples of both successful validation and type mismatch errors.

```elixir
iex(1)> Validator.validate("/history", %{"limit" => "10"})
{:error,"Type mismatch. Expected Integer but got String.", "#/limit"}

iex(2)> Validator.validate("/history", %{"limit" => 10, "offset" => 100})
:ok
```

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

### Configure Live Reloading for Phoenix Swagger (Elixir)

Source: https://github.com/xerions/phoenix_swagger/blob/master/guides/live-reloading.md

This Elixir code snippet configures live reloading for Phoenix Swagger. It specifies patterns for files to watch for changes and lists the compilers to be reloaded, including `:phoenix_swagger`. This setup ensures that swagger files are regenerated and the UI reloaded automatically when relevant files are modified.

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

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

### POST /api/users

Source: https://context7.com/xerions/phoenix_swagger/llms.txt

Create a new user account.

```APIDOC
## POST /api/users

### Description
Create a new user account.

### Method
POST

### Endpoint
/api/users

### Request Body
- **user** (object) - Required - User attributes. Schema: `UserRequest`. Example: `{"user": {"name": "Jane", "email": "jane@example.com"}}`

### Response
#### Success Response (201)
- **data** (object) - The created user details. Schema: `UserResponse`

#### Error Response (422)
Validation errors. Schema: `ErrorResponse`
```

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

### Serve Swagger UI with PhoenixSwagger.Plug.SwaggerUI

Source: https://context7.com/xerions/phoenix_swagger/llms.txt

Configures a Phoenix router to serve the interactive Swagger UI. This plug forwards requests to the `PhoenixSwagger.Plug.SwaggerUI` module, allowing users to explore the API documentation at a specified route.

```elixir
# lib/my_app_web/router.ex
defmodule MyAppWeb.Router do
  use MyAppWeb, :router

  # ... other routes ...

  # Swagger UI route
  scope "/api/swagger" do
    forward "/", PhoenixSwagger.Plug.SwaggerUI,
      otp_app: :my_app,
      swagger_file: "swagger.json"
  end
end

# Now visit http://localhost:4000/api/swagger to see the interactive documentation

# Optional: Configure SwaggerUI with additional options
scope "/api/swagger" do
  forward "/", PhoenixSwagger.Plug.SwaggerUI,
    otp_app: :my_app,
    swagger_file: "swagger.json",
    config_url: "/api/swagger-config.json"  # Optional external config
end
```

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

### GET /history

Source: https://github.com/xerions/phoenix_swagger/blob/master/guides/schema-validation.md

This endpoint retrieves historical data. It supports query parameters for pagination and limiting results.

```APIDOC
## GET /history

### Description
Retrieves historical data with support for offset and limit parameters.

### Method
GET

### Endpoint
/history

### Parameters
#### Query Parameters
- **offset** (integer) - Optional - Offset the list of returned results by this amount. Default is zero.
- **limit** (integer) - Optional - Integer of items to retrieve. Default is 5, maximum is 100.

### Request Example
```json
{
  "limit": 10
}
```

### Response
#### Success Response (200)
- **(structure depends on schema)** - Description of the historical data returned.

#### Response Example
```json
{
  "data": [
    { "event": "some event", "timestamp": "2023-10-27T10:00:00Z" },
    { "event": "another event", "timestamp": "2023-10-27T10:05:00Z" }
  ]
}
```
```

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

### Import Swagger UI Components (JavaScript)

Source: https://github.com/xerions/phoenix_swagger/blob/master/priv/static/README.md

Demonstrates how to import the `SwaggerUIBundle` and `SwaggerUIStandalonePreset` components directly from the `swagger-ui-dist` module using ES module syntax. These are the core components for integrating Swagger UI into your application.

```javascript
import { SwaggerUIBundle, SwaggerUIStandalonePreset } from "swagger-ui-dist"
```

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

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

Source: https://github.com/xerions/phoenix_swagger/blob/master/guides/operations.md

Queries for users within a specific organization. This operation supports paging and filtering, and allows including related resources.

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

#### Request Body
(No request body defined)

### Request Example
(No request example provided)

### Response
#### Success Response (200)
- **Users** (Schema.ref) - Reference to the Users schema.

#### Response Example
(No response example provided)
```

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

### Define API Schemas with Schema.ref and Schema.array

Source: https://context7.com/xerions/phoenix_swagger/llms.txt

Defines API schemas for resources like Posts, Comments, and responses using `Schema.ref` for references and `Schema.array` for lists. This allows for structured API documentation and validation.

```elixir
defmodule MyAppWeb.PostController do
  use MyAppWeb, :controller
  use PhoenixSwagger

  def swagger_definitions do
    %{
            Post: swagger_schema do
              title "Post"
              description "A blog post"
              properties do
                id :integer, "Post ID", required: true
                title :string, "Post title", required: true, maxLength: 255
                body :string, "Post content"
                author Schema.ref(:User), "Post author"
                tags Schema.array(:string), "Post tags"
                comments Schema.array(:Comment), "Post comments"
              end
            end,
            Comment: swagger_schema do
              title "Comment"
              description "A comment on a post"
              properties do
                id :integer, "Comment ID"
                body :string, "Comment text", required: true
                author Schema.ref(:User), "Comment author"
              end
            end,
            PostsResponse: swagger_schema do
              title "PostsResponse"
              type :object
              property :data, Schema.array(:Post), "List of posts"
              property :meta, (Schema.new do
                properties do
                  total_count :integer, "Total number of posts"
                  page :integer, "Current page"
                end
              end)
            end
          }
        end
      end
    end
```
```

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

### Define Detailed Swagger Path with Parameters

Source: https://github.com/xerions/phoenix_swagger/blob/master/guides/operations.md

Demonstrates a more complex `swagger_path` definition including summary, description, produces type, tags, operation ID, paging support, and detailed parameter definitions for path, query, and array types.

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

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

### Generate Swagger Files using Mix Task (Bash)

Source: https://context7.com/xerions/phoenix_swagger/llms.txt

This bash command executes the `mix phx.swagger.generate` task, which reads the configured router and controller information to generate the `swagger.json` file. The output is a JSON file containing the API specification, including paths, definitions, and metadata.

```bash
# Generate swagger files based on configuration
mix phx.swagger.generate

# Output example (priv/static/swagger.json):
# {
#   "swagger": "2.0",
#   "info": {
#     "title": "My App API",
#     "version": "1.0"
#   },
#   "basePath": "/api",
#   "paths": {
#     "/users": {
#       "get": { ... },
#       "post": { ... }
#     }
#   },
#   "definitions": { ... }
# }
```

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

### Configure PhoenixSwagger Output and Router

Source: https://github.com/xerions/phoenix_swagger/blob/master/guides/getting-started.md

Configure the :phoenix_swagger application in your config.exs to specify the output JSON file paths and the corresponding router and endpoint modules. Multiple swagger files can be generated by adding more entries to the swagger_files map.

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

```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]
  }
```

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

### Schema Definitions with swagger_schema

Source: https://context7.com/xerions/phoenix_swagger/llms.txt

Demonstrates how to define reusable schema definitions for request and response bodies using the `swagger_schema` macro and `swagger_definitions/0` function.

```APIDOC
## Defining Schema Definitions with swagger_schema

Define reusable schema definitions in your controller using the `swagger_schema` macro and `swagger_definitions/0` function.

```elixir
defmodule MyAppWeb.UserController do
  use MyAppWeb, :controller
  use PhoenixSwagger

  def swagger_definitions do
    %{ 
      User: swagger_schema do
        title "User"
        description "A user of the application"
        properties do
          id :integer, "User ID", required: true
          name :string, "User name", required: true
          email :string, "Email address", format: :email, required: true
          age :integer, "Age in years", minimum: 0, maximum: 150
          role :string, "User role", enum: ["admin", "user", "guest"]
          inserted_at :string, "Creation timestamp", format: :datetime
          updated_at :string, "Update timestamp", format: :datetime
        end
        example %{
          id: 123,
          name: "John Doe",
          email: "john@example.com",
          age: 30,
          role: "user"
        }
      end,
      UserRequest: swagger_schema do
        title "UserRequest"
        description "POST body for creating a user"
        property :user, Schema.ref(:User), "The user details"
      end,
      UserResponse: swagger_schema do
        title "UserResponse"
        description "Response schema for a single user"
        property :data, Schema.ref(:User), "The user details"
      end,
      UsersResponse: swagger_schema do
        title "UsersResponse"
        description "Response schema for multiple users"
        property :data, Schema.array(:User), "List of users"
      end,
      ErrorResponse: swagger_schema do
        title "ErrorResponse"
        description "Error response"
        properties do
          error :string, "Error message", required: true
          details :object, "Additional error details"
        end
      end
    }
  end
end
```
```

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

### Define JSON-API Schemas with PhoenixSwagger.JsonApi

Source: https://context7.com/xerions/phoenix_swagger/llms.txt

This Elixir snippet showcases how to define JSON-API compliant schemas using `PhoenixSwagger.JsonApi`. It illustrates defining a resource (`ArticleResource`), paginated lists (`Articles`), and single resources (`Article`) with attributes, relationships, and links. This is useful for generating API documentation and ensuring consistent response structures.

```elixir
defmodule MyAppWeb.ArticleController do
  use MyAppWeb, :controller
  use PhoenixSwagger

  def swagger_definitions do
    %{ 
      ArticleResource: JsonApi.resource do
        description "A news article"
        attributes do
          title :string, "Article title", required: true
          body :string, "Article body"
          published_at :string, "Publication date", format: "ISO-8601"
          view_count :integer, "Number of views"
        end
        link :self, "Link to this article"
        relationship :author
        relationship :comments, type: :has_many
        relationship :category, nullable: true
      end,
      Articles: JsonApi.page(:ArticleResource),
      Article: JsonApi.single(:ArticleResource)
    }
  end

  swagger_path :index do
    get "/api/articles"
    summary "List Articles"
    produces "application/vnd.api+json"
    paging size: "page[size]", number: "page[number]"
    response 200, "OK", Schema.ref(:Articles)
  end

  swagger_path :show do
    get "/api/articles/{id}"
    summary "Get Article"
    produces "application/vnd.api+json"
    parameter :id, :path, :string, "Article ID", required: true
    parameter :include, :query, :string, "Related resources to include",
      enum: ["author", "comments", "category"]
    response 200, "OK", Schema.ref(:Article)
  end
end

# Generated JSON-API response schema structure:
# {
#   "data": {
#     "type": "article",
#     "id": "1",
#     "attributes": {
#       "title": "Hello World",
#       "body": "...",
#       "published_at": "2024-01-15T10:30:00Z"
#     },
#     "relationships": {
#       "author": {
#         "links": { "self": "...", "related": "..." },
#         "data": { "type": "user", "id": "42" }
#       },
#       "comments": {
#         "data": [
#           { "type": "comment", "id": "1" },
#           { "type": "comment", "id": "2" }
#         ]
#       }
#     },
#     "links": { "self": "/api/articles/1" }
#   },
#   "included": [...] 
# }
```

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

### Create Admin User API

Source: https://context7.com/xerions/phoenix_swagger/llms.txt

This endpoint allows for the creation of an admin user. It requires Bearer token authentication and OAuth2 with 'write:users' scope.

```APIDOC
## POST /api/admin/users

### Description
Creates an admin user.

### Method
POST

### Endpoint
/api/admin/users

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None specified in the provided documentation.

### Request Example
```json
{
  "example": "No request body example provided"
}
```

### Response
#### Success Response (201)
- **message** (string) - Indicates successful creation.

#### Response Example
```json
{
  "example": "Created"
}
```
```

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

### Generate Swagger File with Mix Task

Source: https://github.com/xerions/phoenix_swagger/blob/master/guides/swagger-ui.md

This command uses the `mix phx.swagger.generate` task to create a swagger specification file. This file is typically placed in the `priv/static` directory of your Phoenix application.

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

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

### Integrate PhoenixSwagger SchemaTest in Controller Tests (Elixir)

Source: https://github.com/xerions/phoenix_swagger/blob/master/guides/test-helpers.md

Demonstrates how to integrate the PhoenixSwagger.SchemaTest mixin into controller test files. This requires specifying the path to the swagger JSON file.

```elixir
defmodule YourApp.UserControllerTest do
  use YourApp.ConnCase, async: true
  use PhoenixSwagger.SchemaTest, "priv/static/swagger.json"

```

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

### Create Polymorphic Schemas with allOf and discriminator in Elixir

Source: https://context7.com/xerions/phoenix_swagger/llms.txt

This Elixir code defines polymorphic schemas using 'allOf' for composition and 'discriminator' for type differentiation in Phoenix Swagger. It sets up a base 'Pet' schema and derived 'Dog' and 'Cat' schemas, demonstrating how to model inheritance and specialized properties for different pet types.

```elixir
def swagger_definitions do
  %{
    Pet: swagger_schema do
      title "Pet"
      description "Base pet schema"
      type :object
      discriminator :pet_type
      properties do
        pet_type :string, "Type of pet", required: true
        name :string, "Pet name", required: true
      end
    end,
    Dog: swagger_schema do
      title "Dog"
      description "A dog"
      all_of [
        Schema.ref(:Pet),
        Schema.new do
          properties do
            breed :string, "Dog breed"
            bark_volume :string, "How loud", enum: ["quiet", "normal", "loud"]
          end
        end
      ]
    end,
    Cat: swagger_schema do
      title "Cat"
      description "A cat"
      all_of [
        Schema.ref(:Pet),
        Schema.new do
          properties do
            indoor :boolean, "Indoor cat", default: true
            declawed :boolean, "Is declawed"
          end
        end
      ]
    end
  }
end
```

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

### Generate Swagger Path for Index Action

Source: https://github.com/xerions/phoenix_swagger/blob/master/guides/operations.md

Generates a Swagger specification for a Phoenix controller's index action using the `swagger_path` macro. It defines the HTTP method, path, and expected responses.

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

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

### Configure PhoenixSwagger Compiler

Source: https://github.com/xerions/phoenix_swagger/blob/master/guides/getting-started.md

Append :phoenix_swagger to the compilers list in your mix.exs project configuration. This ensures swagger files are automatically updated during compilation.

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

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

### Apply Reused Swagger Parameters in Phoenix Controller

Source: https://github.com/xerions/phoenix_swagger/blob/master/guides/reusing-swagger-parameters.md

This Elixir code demonstrates how to apply the reusable common parameters defined in the `CommonParameters` module within a Phoenix controller's `swagger_path` definition. It shows how to include authorization and sorting parameters.

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

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

### JSON-API Schema Helpers

Source: https://context7.com/xerions/phoenix_swagger/llms.txt

This section explains how to use the `PhoenixSwagger.JsonApi` module to define JSON:API compliant schema definitions for your API resources.

```APIDOC
## GET /api/articles

### Description
Lists all articles, supporting pagination.

### Method
GET

### Endpoint
/api/articles

### Parameters
#### Query Parameters
- **page[size]** (integer) - Optional - The number of articles per page.
- **page[number]** (integer) - Optional - The page number to retrieve.
#### Headers
- **Accept** (string) - Required - `application/vnd.api+json`

### Response
#### Success Response (200)
- **data** (array) - An array of article resources.
- **links** (object) - Pagination links.

#### Response Example
```json
{
  "data": [
    {
      "type": "article",
      "id": "1",
      "attributes": {
        "title": "Hello World",
        "body": "...",
        "published_at": "2024-01-15T10:30:00Z"
      },
      "links": {
        "self": "/api/articles/1"
      }
    }
  ],
  "links": {
    "self": "/api/articles?page[number]=1&page[size]=10"
  }
}
```

## GET /api/articles/{id}

### Description
Retrieves a specific article by its ID, with options to include related resources.

### Method
GET

### Endpoint
/api/articles/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the article to retrieve.
#### Query Parameters
- **include** (string) - Optional - Comma-separated list of related resources to include (e.g., `author`, `comments`, `category`).
  - **Enum**: `["author", "comments", "category"]`
#### Headers
- **Accept** (string) - Required - `application/vnd.api+json`

### Response
#### Success Response (200)
- **data** (object) - The article resource.
- **included** (array) - An array of included related resources.

#### Response Example
```json
{
  "data": {
    "type": "article",
    "id": "1",
    "attributes": {
      "title": "Hello World",
      "body": "...",
      "published_at": "2024-01-15T10:30:00Z"
    },
    "relationships": {
      "author": {
        "links": {"self": "...", "related": "..."},
        "data": {"type": "user", "id": "42"}
      },
      "comments": {
        "data": [
          {"type": "comment", "id": "1"},
          {"type": "comment", "id": "2"}
        ]
      }
    },
    "links": {"self": "/api/articles/1"}
  },
  "included": [
    {
      "type": "user",
      "id": "42",
      "attributes": {"name": "John Doe"}
    }
  ]
}
```
```

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

### User Resource Schema

Source: https://github.com/xerions/phoenix_swagger/blob/master/guides/json-api-helpers.md

Describes a JSON:API resource object for a user, including attributes, links, and relationships.

```APIDOC
## JSON:API Resource Object: UserResource

### Description
A user that may have one or more supporter pages.

### Method
N/A (Schema definition)

### Endpoint
N/A (Schema definition)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **type** (string) - The resource type.
- **id** (string) - The resource identifier.
- **attributes** (object) - A map of resource 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** (object) - Users address
- **links** (object) - Links associated with the resource.
  - **self** (string) - The link to this user resource
- **relationships** (object) - Relationships to other resources.
  - **preferences** (object) - Relationship to preferences.
  - **posts** (object) - Relationship to posts, type: has_many

#### Response Example
```json
{
  "data": {
    "type": "UserResource",
    "id": "some-user-id",
    "attributes": {
      "phone": "123-456-7890",
      "full_name": "John Doe",
      "user_updated_at": "2023-10-27T10:00:00Z",
      "user_created_at": "2023-01-01T09:00:00Z",
      "email": "john.doe@example.com",
      "birthday": "1990-05-15",
      "address": {
        "street": "123 Main St",
        "city": "Anytown"
      }
    },
    "links": {
      "self": "/api/v1/users/some-user-id"
    },
    "relationships": {
      "preferences": {
        "data": {
          "type": "PreferencesResource",
          "id": "user-prefs-id"
        }
      },
      "posts": {
        "data": [
          {
            "type": "PostResource",
            "id": "post-1"
          },
          {
            "type": "PostResource",
            "id": "post-2"
          }
        ]
      }
    }
  }
}
```
```

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

### Polymorphic Schemas

Source: https://context7.com/xerions/phoenix_swagger/llms.txt

Defines polymorphic schemas using `allOf` and `discriminator` for inheritance patterns.

```APIDOC
## Polymorphic Schemas

### Pet Schema (Base)
**Description**: Base pet schema.
**Properties**:
- **pet_type** (string) - Required - Type of pet
- **name** (string) - Required - Pet name
**Discriminator**: pet_type

### Dog Schema
**Description**: A dog.
**All Of**: [Schema.ref(:Pet)]
**Properties**:
- **breed** (string) - Dog breed
- **bark_volume** (string) - How loud (enum: ["quiet", "normal", "loud"])

### Cat Schema
**Description**: A cat.
**All Of**: [Schema.ref(:Pet)]
**Properties**:
- **indoor** (boolean) - Indoor cat (default: true)
- **declawed** (boolean) - Is declawed
```

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

### Add Swagger UI Scope to Phoenix Router

Source: https://github.com/xerions/phoenix_swagger/blob/master/guides/swagger-ui.md

This Elixir code snippet demonstrates how to add a scope to your Phoenix router to serve Swagger UI. It forwards requests to `PhoenixSwagger.Plug.SwaggerUI`, specifying the OTP app and the swagger file to use. Ensure the `otp_app` and `swagger_file` parameters match your application's configuration.

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

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

### Apply Per-Operation Security (Elixir)

Source: https://context7.com/xerions/phoenix_swagger/llms.txt

This Elixir code demonstrates how to apply specific security requirements to individual API operations within a Phoenix Swagger controller. It shows how to combine different security schemes, like Bearer token and OAuth2 with specific scopes, for a particular route.

```elixir
swagger_path :create do
  post "/api/admin/users"
  summary "Create Admin User"
  security [%{Bearer: []}, %{OAuth2: ["write:users"]}]
  response 201, "Created"
end
```

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

### Configure JSON Library for PhoenixSwagger

Source: https://github.com/xerions/phoenix_swagger/blob/master/guides/getting-started.md

Optionally, configure the JSON library to be used by PhoenixSwagger. By default, it might use a built-in or common library, but you can explicitly set it.

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

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

### Define API Information in Phoenix Router

Source: https://github.com/xerions/phoenix_swagger/blob/master/guides/getting-started.md

Implement the swagger_info/0 function in your Phoenix router module to provide essential API metadata like version and title. This function should return a map containing the API's information. Additional fields like basePath and tags can also be included.

```elixir
defmodule MyApp.Router do
  use MyApp.Web, :router

  pipeline :api do
    plug :accepts, ["json"]
  end

  scope "/api", MyApp do
    pipe_through :api
    resources "/users", UserController
  end

def swagger_info do
  %{info: %{version: "1.0", title: "My App"}}
end
end
```

```elixir
def swagger_info do
  %{ 
    basePath: "/api",
    info: %{..},
    tags: [%{name: "Users", description: "Operations about Users"}]
  }
end
```
Tokens:
Raw