Open API Spex

The PlugApp example is organized into three main components to demonstrate how open_api_spex integrates with a Plug-based API:

• API Specification: lib/plug_app/api_spec.ex defines the outline of the OpenAPI specification.
• Schemas: lib/plug_app/schemas.ex contains the modules used for defining request and response schemas.
• Routing: lib/plug_app/router.ex contains the Plug router that handles incoming requests.

If your API requires authorization, define security schemes within the components key of your main spec. You can then declare the security requirements globally in the main spec or per individual operation.

# Define the scheme in components
components: %Components{
  securitySchemes: %{"authorization" => %SecurityScheme{type: "http", scheme: "bearer"}}
}

# Declare it globally in the spec
security: [%{"authorization" => []}]

The OpenApiSpex.TestAssertions module provides tools to ensure your API implementation stays in sync with your documentation.

Asserting that an example matches a schema

Use assert_schema/2 to verify that the example data generated by a schema matches the overall API specification.

Asserting that a response matches a schema

Use assert_schema/2 to verify that the actual JSON response returned by a controller matches the expected schema in your API spec.

import OpenApiSpex.TestAssertions

# Validate an example
assert_schema(schema.example, "UsersResponse", api_spec)

# Validate a controller response
assert_schema(json_response, "UsersResponse", api_spec)

You can import existing JSON or YAML encoded OpenAPI schemas and cast them into an %OpenApi{} struct using OpenApiSpex.OpenApi.Decode.decode/1.

Warning: This functionality converts Strings into Atoms, which may be vulnerable to DoS attacks. Only load schemas from known files during application startup; do not load them dynamically from external sources at runtime.

# Importing an existing JSON encoded schema
open_api_spec_from_json = "encoded_schema.json"
  |> File.read!()
  |> Jason.decode!()
  |> OpenApiSpex.OpenApi.Decode.decode()

# Importing an existing YAML encoded schema
open_api_spec_from_yaml = "encoded_schema.yaml"
  |> YamlElixir.read_all_from_file!()
  |> List.first()
  |> OpenApiSpex.OpenApi.Decode.decode()

To run the demonstration Phoenix API application, execute the following commands in sequence to fetch dependencies, generate the OpenAPI specification, set up the database, and start the server:

mix deps.get
mix phoenix_app_web.open_api_spec
mix ecto.create
mix ecto.migrate
mix phx.server

To run the PlugApp demonstration, which shows how to use open_api_spex within a Plug API application, execute the following commands in your terminal to install dependencies, set up the database, and start the server:

1. Fetch dependencies: mix deps.get
2. Create the database: mix ecto.create
3. Run migrations: mix ecto.migrate
4. Start the application: mix run --no-halt

Once running, you can view the generated Swagger UI at http://localhost:4000/swaggerui.

Once the PhoenixApp server is running, you can interact with and view the generated OpenAPI documentation via the Swagger UI endpoint at:

http://localhost:4000/swaggerui

To use Open API Spex in your Elixir project, add :open_api_spex to your mix.exs dependencies.

def deps do
  [
    {:open_api_spex, "~> 3.21"}
  ]
end

In OpenApiSpex.Paths, the t() type represents the OpenAPI Paths Object. It is a map where the keys are the relative URL paths (strings) and the values are PathItem.t() objects containing the operations (GET, POST, etc.) available at that path.

Note that paths are appended to the URL from the Server Object to construct full URLs. The Paths object may be empty if ACL constraints apply.