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
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
SwaggerUIwithPlug.CSRFProtection
See the changelog for more details.
7
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.
6
moxley
Version 3.10.0 is released!
- Feature: Support OAuth2 for swagger-ui (#217)
- Feature: Support
defaultresponse type in responses (#301) - Feature: Allow overriding
x-structinOpenApiSpex.schema/1(#304) - Feature: Ability to specify
deprecatedin ControllerSpec operation (#296) - Feature:
:struct?and:derive?options inOpenApiSpex.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
:formatvalue 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
6
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)
5
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
OpenApidocument and theInfostructs -
Server.from_endpointnow uses the Phoenix API instead of the endpoint config to determine the URL - Compatibility with Phoenix 1.4.7 Router modules
4
Popular in Libraries
I’ve just released stable versions of my Prometheus Elixir libs:
Elixir client [docs];
Ecto collector [docs];
Plugs instrumenter/Export...
New
If you would like to migrate away from node/npm/webpack while still using sass, the dart_sass package provides a installer and runner for...
New
Another small library today.
PersistentEts
Hex: persistent_ets | Hex
GitHub: GitHub - michalmuskala/persistent_ets
Ets table backed by...
New
Hello everyone,
I wrote a small library today called MapDiff.
It returns a map listing the (smallest amount of) changes to get from map...
New
I’ve just released the first version of Snap, an Elasticsearch client. It borrows ideas about application structure and process managemen...
New
While not as prevalent as in imperative languages, arrays (collections with efficient random element access) are still very useful in Eli...
New
Expat is a tiny experiment I did for extracting patterns and being able to reuse them (compose and share patterns between elixir librarie...
New
Here is my first stab at this. README pasted below.
https://github.com/Hal9000/elixir_random
Comments and critiques are welcome.
Th...
New
Let’s write a database! Well not really, but I think it’s a little sad that there doesn’t seem to be a simple in-memory distributed KV da...
New
Could not wait for the missing Elixir ML libraries to appear, so, I wrote one myself, taking https://github.com/sdwolfz/exlearn as a foun...
New
Other popular topics
Here are few pieces of (common) Linux knowledge that we use for reasonably small one server apps. We use Ubuntu but this should work for ...
New
Hello!
tl;dr Announcing Oban, an Ecto based job processing library with a focus on reliability and historical observability.
After spen...
New
This post is a wiki (feel free to hit the edit button near the bottom right of this post to add your own changes!)
This post collects co...
New
I am VERY much an elixir newbie. I have taken one elixir course and one phoenix course on Udemy. During that course, I saw the instructor...
New
You’re a programmer, so you don’t need spoon feeding with the conventional drivel about “this is an integer.” No. You need to know what’s...
New
Hello, can anybody help here..? I have a list of players and I what to delete an element, but every for loop the list is reverting to ori...
New
Could someone help me? I'm making my first elixir program, number guessing game. I can't figure out how to convert the user's guess from ...
New
None of the current solutions worked well for me, so I went ahead and built a user management system from scratch.
This project took far...
New
After calling mix ecto.create I get this error:
17:00:32.162 [error] GenServer #PID<0.412.0> terminating
** (Postgrex.Error) FATAL...
New
This post is an instruction guide to help you setup your Neovim for Elixir development from scratch. It includes general information on h...
New
Latest on Elixir Forum
Sponsor Spotlight
Catch errors, track performance, monitor hosts and more.
Categories:
Sub Categories:
Forums
Our Sponsors
Build Elixir applications with speed and confidence.
Supporting innovation across the BEAM ecosystem.
We build reliable cloud platforms for business-critical systems.
Catch errors, track performance, monitor hosts and more.
Practical resources that improve the lives of professional developers.
Producing high quality Elixir screencasts since 2017.
The deployment platform built for Elixir: PaaS ease, VPS control.
Courses that'll move you from confusion to "Aha, now I get it!"