mbuhot

OpenApiSpex - OpenAPI / Swagger 3.0 for Plug APIs

Leverage Open Api 3.0 (Swagger) to document, test, validate and explore your Plug and Phoenix APIs.

Generate and serve a JSON Open API (swagger) document from your code
Use the spec to cast request params to well defined schema structs
Validate params against schemas, eliminate bad requests before they hit your controllers
Validate responses against schemas in tests, ensuring your docs are accurate and reliable
Explore the API interactively with with SwaggerUI

Github: https://github.com/mbuhot/open_api_spex
Docs: https://hexdocs.pm/open_api_spex/
Hex: https://hex.pm/packages/open_api_spex

Integrating with phoenix controllers:

  @spec open_api_operation(atom) :: Operation.t
  def open_api_operation(action), do: apply(__MODULE__, :"#{action}_operation", [])

  @spec show_operation() :: Operation.t
  def show_operation() do
    %Operation{
      tags: ["users"],
      summary: "Show user",
      description: "Show a user by ID",
      operationId: "UserController.show",
      parameters: [
        Operation.parameter(:id, :path, :integer, "User ID", example: 123)
      ],
      responses: %{
        200 => Operation.response("User", "application/json", UserResponse)
      }
    }
  end
  def show(conn, %{"id" => id}) do
    {:ok, user} = MyApp.Users.find_by_id(id)
    json(conn, 200, user)
  end

Cast and validate params:

  plug OpenApiSpex.Plug.Cast
  plug OpenApiSpex.Plug.Validate

  def open_api_operation(action) do
    apply(__MODULE__, :"#{action}_operation", [])
  end

  def create_operation do
    import Operation
    %Operation{
      tags: ["users"],
      summary: "Create user",
      description: "Create a user",
      operationId: "UserController.create",
      parameters: [],
      requestBody: request_body("The user attributes", "application/json", UserRequest),
      responses: %{
        201 => response("User", "application/json", UserResponse)
      }
    }
  end

  def create(conn, request = %UserRequest{user: %User{name: name, email: email, birthday: birthday = %Date{}}}) do
    ...  
end

54 comments

#plug #swagger #open_api_spex

79 14209 54

2024-04-29 06:31:21 UTC

Most Liked

mbuhot

Version 3.2.0 released.

Lots of internal improvements and some new features thanks to the wonderful contributors, particularly @moxley and the team at Ghost Group / Weedmaps.

Highlights:

Jason library support for JSON serialization
Improved memory usage
Improved error messages and validations
Integrate SwaggerUI with Plug.CSRFProtection

See the changelog for more details.

Post #6

moxley

Version 3.5.0 is released!

This version has a lot of changes from the last several months. Highlights:

Ability to import Open API documents into OpenApiSpex, as an alternative to defining specs using using OpenApiSpex’ Elixir syntax.
Experimental support for ExDoc-based operation specs. Use doc tags in your controller to define operations instead of defining callback functions.
Improved Open API compliance and bug fixes for casting and validations
Deprecate the legacy cast & validate implementation for the newer Cast module.

Thank you to @mbuhot for letting me manage the release.

Post #10

moxley

Version 3.10.0 is released!

Feature: Support OAuth2 for swagger-ui (#217)
Feature: Support default response type in responses (#301)
Feature: Allow overriding x-struct in OpenApiSpex.schema/1 (#304)
Feature: Ability to specify deprecated in ControllerSpec operation (#296)
Feature: :struct? and :derive? options in OpenApiSpex.schema/1 (#312)
Feature: OpenApiSpex.add_schemas/2 (#314)
Enhancement: Remove api_spec data from Conn (#286)
Enhancement: More informative errors for bad schema (#288, #284, #287)
Fix: Convert :format value to atom when decoding schema file (#293)
Fix: Type spec in OpenApiSpex.Info
Fix: Elixir Formatter rules in published package (#306)
Docs: Fix spelling error in example code (#295)
Docs: Fix type in README (#297)
Docs: Fix links and punctuation in README (#298)
Docs: Promote ControlerSpecs as the preferred API for controller operations (#311)

As always, a huge thank you to all the contributors and maintainers for keeping the project going

Post #46

moxley

Version 3.6.0 is released!

This release include some enhancements and important bug fixes:

Feature: Improved inspect output of %Schema{} (#193)
Feature: Auto-populate schema title from module name (#192)
Feature: Derive Operation ID from meta in ExDoc specs (#195)
Fix: Validation of array minItems ignores empty array (#179)
Fix: Add minimum/maximum validation for number properties (#181)
Fix: Properly validate header params (#184)
Fix: Support free-form query parameters (#171)
Fix: Resolve schema modules from Response in Components (#186)

Post #11

mbuhot

Version 3.4.0 released.

This version is required when using Phoenix 1.4.7+ and the OpenApiSpex.Paths.from_router/1 function.

Highlights:

Open API extensions can be added to the OpenApi document and the Info structs
Server.from_endpoint now uses the Phoenix API instead of the endpoint config to determine the URL
Compatibility with Phoenix 1.4.7 Router modules

Post #7