PhoenixSwagger

PhoenixSwagger is a library designed to integrate Swagger capabilities into the Phoenix web framework. Its core functionalities include:

• API Specification Generation: Automatically generate a Swagger API specification derived from your Phoenix router and controllers.
• Swagger UI: Serve the Swagger UI interface to interactively explore and test your API.
• Request Validation: Validate incoming requests against defined parameter schemas.
• Response Validation: Validate API responses against schemas during your test suites.

The host value in your generated Swagger file is derived from your Phoenix Endpoint url configuration.

If your host is configured dynamically (using {:systems, "VAR"} or the :load_from_system_env flag), PhoenixSwagger will omit the host field from the generated JSON. In this case, SwaggerUI will default to using the same host that is serving the swagger file itself.

# config.exs
config :my_app, MyApp.Web.Endpoint,
  url: [host: "localhost"] # Results in "host": "localhost:4000" in swagger

# prod.exs
config :my_app, MyApp.Web.Endpoint,
  load_from_system_env: true, # host will be omitted from swagger
  url: [host: "example.com", port: 80]

To use PhoenixSwagger in your Phoenix application, follow the official getting started guide. The library provides integration for generating Swagger API specifications from Phoenix routers and controllers, serving Swagger UI, validating requests against parameter schemas, and validating responses against schemas in tests.

# Refer to the getting started guide for specific installation steps:
# https://hexdocs.pm/phoenix_swagger/getting-started.html

To automatically validate input parameters for all routes within a pipeline, add PhoenixSwagger.Plug.Validate to your Phoenix router pipeline.

Behavior

• On Success: The request proceeds to the controller.
• On Failure: The Plug halts the connection and returns a 400 status code (configurable) with a JSON error body containing the path and message.
• Skipping Validation: If you need to bypass validation for a specific request, set conn.private[:phoenix_swagger][:valid] to true before the Plug is reached.

Configuration

• Use the :validation_failed_status parameter to change the HTTP status code returned on validation errors.

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

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

Use the swagger_path/2 macro within a Phoenix controller to generate a Swagger specification for a specific action. The macro requires the name of the controller action and a do block containing the Swagger DSL.

Parameters:

1. Action Name: The atom representing the controller action (e.g., :index).
2. DSL Block: A block using PhoenixSwagger.Path functions to define the endpoint's metadata, parameters, and responses.

Note: The PhoenixSwagger.Path.delete/2 function may clash with your controller's own delete/2 function. If you need to customize the route for Swagger, use a qualified function call to avoid name collisions.

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

To generate a Swagger specification file, configure the :phoenix_swagger key in your application configuration. Map the desired output path in priv/static to the router responsible for the API.

Example configuration:

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

After configuring, run the following Mix task to generate the file:

mix phx.swagger.generate

To enable effective validation using PhoenixSwagger.SchemaTest, you must explicitly mark properties as required in your swagger definitions using the required: true option. If properties are not marked as required, the schema validator may not correctly enforce their presence in controller responses.

  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

To see phoenix_swagger in action using the provided simple demo application, follow these steps to install dependencies, set up the database, compile the source (which triggers swagger generation), and start the server.

1. Install dependencies: mix deps.get
2. Create the database: mix ecto.setup
3. Compile source and generate swagger: mix compile
4. Start the Phoenix server: mix phx.server
5. Access the Swagger UI: Open your browser and navigate to http://localhost:4000/api/swagger/.

To install PhoenixSwagger, add it to your mix.exs dependencies. You may also optionally add ex_json_schema if you require the schema validation plug and test helpers.

To ensure swagger files are automatically updated every time your application is compiled, append :phoenix_swagger to your project's compilers list.

# mix.exs

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

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