Page MenuHomePhorge
Files F112407

No OneTemporary
Actions

Size
12 KB
Referenced Files
None
Subscribers
None

View Options

diff --git a/lib/open_api_spex/plug/cast.ex b/lib/open_api_spex/plug/cast.ex
index f93db02..3d5ed4a 100644
--- a/lib/open_api_spex/plug/cast.ex
+++ b/lib/open_api_spex/plug/cast.ex
@@ -1,28 +1,44 @@
defmodule OpenApiSpex.Plug.Cast do
+ @moduledoc """
+ Module plug that will cast the `Conn.params` according to the schemas defined for the operation.
+
+ The operation_id can be given at compile time as an argument to `init`:
+
+ plug OpenApiSpex.Plug.Cast, operation_id: "MyApp.ShowUser"
+
+ For phoenix applications, the operation_id can be obtained at runtime automatically.
+
+ defmodule MyAppWeb.UserController do
+ use Phoenix.Controller
+ plug OpenApiSpex.Plug.Cast
+ ...
+ end
+ """
+
@behaviour Plug
alias Plug.Conn
@impl Plug
def init(opts), do: opts
@impl Plug
def call(conn = %{private: %{open_api_spex: private_data}}, operation_id: operation_id) do
spec = private_data.spec
operation = private_data.operation_lookup[operation_id]
content_type = Conn.get_req_header(conn, "content-type") |> Enum.at(0)
private_data = Map.put(private_data, :operation_id, operation_id)
conn = Conn.put_private(conn, :open_api_spex, private_data)
case OpenApiSpex.cast(spec, operation, conn.params, content_type) do
{:ok, params} -> %{conn | params: params}
{:error, reason} ->
conn
|> Plug.Conn.send_resp(422, "#{reason}")
|> Plug.Conn.halt()
end
end
def call(conn = %{private: %{phoenix_controller: controller, phoenix_action: action}}, _opts) do
call(conn, operation_id: controller.open_api_operation(action).operationId)
end
end
\ No newline at end of file
diff --git a/lib/open_api_spex/plug/put_api_spec.ex b/lib/open_api_spex/plug/put_api_spec.ex
index 98b2c0d..ee2c139 100644
--- a/lib/open_api_spex/plug/put_api_spec.ex
+++ b/lib/open_api_spex/plug/put_api_spec.ex
@@ -1,28 +1,37 @@
defmodule OpenApiSpex.Plug.PutApiSpec do
+ @moduledoc """
+ Module plug that calls a given module to obtain the Api Spec and store it as private in the Conn.
+
+ This allows downstream plugs to use the API spec for casting, validating and rendering.
+
+ ## Example
+
+ plug OpenApiSpex.Plug.PutApiSpec, module: MyAppWeb.ApiSpec
+ """
@behaviour Plug
@impl Plug
def init(opts = [module: _mod]), do: opts
@impl Plug
def call(conn, module: mod) do
spec = %OpenApiSpex.OpenApi{} = mod.spec()
private_data =
conn
|> Map.get(:private)
|> Map.get(:open_api_spex, %{})
|> Map.put(:spec, spec)
|> Map.put(:operation_lookup, build_operation_lookup(spec))
Plug.Conn.put_private(conn, :open_api_spex, private_data)
end
defp build_operation_lookup(spec = %OpenApiSpex.OpenApi{}) do
spec
|> Map.get(:paths)
|> Stream.flat_map(fn {_name, item} -> Map.values(item) end)
|> Stream.filter(fn x -> match?(%OpenApiSpex.Operation{}, x) end)
|> Stream.map(fn operation -> {operation.operationId, operation} end)
|> Enum.into(%{})
end
end
\ No newline at end of file
diff --git a/lib/open_api_spex/plug/render_spec.ex b/lib/open_api_spex/plug/render_spec.ex
index 78c5ac0..b1e75dd 100644
--- a/lib/open_api_spex/plug/render_spec.ex
+++ b/lib/open_api_spex/plug/render_spec.ex
@@ -1,16 +1,36 @@
defmodule OpenApiSpex.Plug.RenderSpec do
@moduledoc """
- Renders the API spec stored earlier in the Conn by `OpenApiSpex.Plug.PutApiSpec`
+ Renders the API spec as a JSON response.
+
+ The API spec must be stored in the conn by `OpenApiSpex.Plug.PutApiSpec` earlier in the plug pipeline.
+
+ ## Example
+
+ defmodule MyAppWeb.Router do
+ use Phoenix.Router
+ alias MyAppWeb.UserController
+
+ pipeline :api do
+ plug :accepts, ["json"]
+ plug OpenApiSpex.Plug.PutApiSpec, module: MyAppWeb.ApiSpec
+ end
+
+ scope "/api" do
+ pipe_through :api
+ resources "/users", UserController, only: [:create, :index, :show]
+ get "/openapi", OpenApiSpex.Plug.RenderSpec, []
+ end
+ end
"""
@behaviour Plug
@impl Plug
def init(opts), do: opts
@impl Plug
def call(conn, _opts) do
conn
|> Plug.Conn.put_resp_content_type("application/json")
|> Plug.Conn.send_resp(200, Poison.encode!(conn.private.open_api_spex.spec))
end
end
\ No newline at end of file
diff --git a/lib/open_api_spex/plug/swagger_ui.ex b/lib/open_api_spex/plug/swagger_ui.ex
index 00d78da..a6b28f4 100644
--- a/lib/open_api_spex/plug/swagger_ui.ex
+++ b/lib/open_api_spex/plug/swagger_ui.ex
@@ -1,112 +1,134 @@
defmodule OpenApiSpex.Plug.SwaggerUI do
+ @moduledoc """
+ Module plug that serves SwaggerUI.
+
+ The full path to the API spec must be given as a plug option.
+ The API spec should be served at the given path, see `OpenApiSpex.Plug.RenderSpec`
+
+ ## Example
+
+ scope "/" do
+ pipe_through :browser # Use the default browser stack
+
+ get "/", MyAppWeb.PageController, :index
+ get "/swaggerui", OpenApiSpex.Plug.SwaggerUI, path: "/api/openapi"
+ end
+
+ # Other scopes may use custom stacks.
+ scope "/api" do
+ pipe_through :api
+ resources "/users", MyAppWeb.UserController, only: [:index, :create, :show]
+ get "/openapi", OpenApiSpex.Plug.RenderSpec, :show
+ end
+ """
@behaviour Plug
@html """
<!-- HTML for static distribution bundle build -->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Swagger UI</title>
<link href="https://fonts.googleapis.com/css?family=Open+Sans:400,700|Source+Code+Pro:300,600|Titillium+Web:400,600,700" rel="stylesheet">
<link rel="stylesheet" type="text/css" href="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.2.1/swagger-ui.css" >
<link rel="icon" type="image/png" href="./favicon-32x32.png" sizes="32x32" />
<link rel="icon" type="image/png" href="./favicon-16x16.png" sizes="16x16" />
<style>
html
{
box-sizing: border-box;
overflow: -moz-scrollbars-vertical;
overflow-y: scroll;
}
*,
*:before,
*:after
{
box-sizing: inherit;
}
body {
margin:0;
background: #fafafa;
}
</style>
</head>
<body>
<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" style="position:absolute;width:0;height:0">
<defs>
<symbol viewBox="0 0 20 20" id="unlocked">
<path d="M15.8 8H14V5.6C14 2.703 12.665 1 10 1 7.334 1 6 2.703 6 5.6V6h2v-.801C8 3.754 8.797 3 10 3c1.203 0 2 .754 2 2.199V8H4c-.553 0-1 .646-1 1.199V17c0 .549.428 1.139.951 1.307l1.197.387C5.672 18.861 6.55 19 7.1 19h5.8c.549 0 1.428-.139 1.951-.307l1.196-.387c.524-.167.953-.757.953-1.306V9.199C17 8.646 16.352 8 15.8 8z"></path>
</symbol>
<symbol viewBox="0 0 20 20" id="locked">
<path d="M15.8 8H14V5.6C14 2.703 12.665 1 10 1 7.334 1 6 2.703 6 5.6V8H4c-.553 0-1 .646-1 1.199V17c0 .549.428 1.139.951 1.307l1.197.387C5.672 18.861 6.55 19 7.1 19h5.8c.549 0 1.428-.139 1.951-.307l1.196-.387c.524-.167.953-.757.953-1.306V9.199C17 8.646 16.352 8 15.8 8zM12 8H8V5.199C8 3.754 8.797 3 10 3c1.203 0 2 .754 2 2.199V8z"/>
</symbol>
<symbol viewBox="0 0 20 20" id="close">
<path d="M14.348 14.849c-.469.469-1.229.469-1.697 0L10 11.819l-2.651 3.029c-.469.469-1.229.469-1.697 0-.469-.469-.469-1.229 0-1.697l2.758-3.15-2.759-3.152c-.469-.469-.469-1.228 0-1.697.469-.469 1.228-.469 1.697 0L10 8.183l2.651-3.031c.469-.469 1.228-.469 1.697 0 .469.469.469 1.229 0 1.697l-2.758 3.152 2.758 3.15c.469.469.469 1.229 0 1.698z"/>
</symbol>
<symbol viewBox="0 0 20 20" id="large-arrow">
<path d="M13.25 10L6.109 2.58c-.268-.27-.268-.707 0-.979.268-.27.701-.27.969 0l7.83 7.908c.268.271.268.709 0 .979l-7.83 7.908c-.268.271-.701.27-.969 0-.268-.269-.268-.707 0-.979L13.25 10z"/>
</symbol>
<symbol viewBox="0 0 20 20" id="large-arrow-down">
<path d="M17.418 6.109c.272-.268.709-.268.979 0s.271.701 0 .969l-7.908 7.83c-.27.268-.707.268-.979 0l-7.908-7.83c-.27-.268-.27-.701 0-.969.271-.268.709-.268.979 0L10 13.25l7.418-7.141z"/>
</symbol>
<symbol viewBox="0 0 24 24" id="jump-to">
<path d="M19 7v4H5.83l3.58-3.59L8 6l-6 6 6 6 1.41-1.41L5.83 13H21V7z"/>
</symbol>
<symbol viewBox="0 0 24 24" id="expand">
<path d="M10 18h4v-2h-4v2zM3 6v2h18V6H3zm3 7h12v-2H6v2z"/>
</symbol>
</defs>
</svg>
<div id="swagger-ui"></div>
<script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.2.1/swagger-ui-bundle.js"> </script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/swagger-ui/3.2.1/swagger-ui-standalone-preset.js"> </script>
<script>
window.onload = function() {
// Build a system
const api_spec_url = new URL(window.location);
api_spec_url.pathname = "<%= path %>";
api_spec_url.hash = "";
const ui = SwaggerUIBundle({
url: api_spec_url.href,
dom_id: '#swagger-ui',
deepLinking: true,
presets: [
SwaggerUIBundle.presets.apis,
SwaggerUIStandalonePreset
],
plugins: [
SwaggerUIBundle.plugins.DownloadUrl
],
layout: "StandaloneLayout"
})
window.ui = ui
}
</script>
</body>
</html>
"""
@impl Plug
def init(path: path), do: [html: EEx.eval_string(@html, path: path)]
@impl Plug
def call(conn, html: html) do
conn
|> Plug.Conn.put_resp_content_type("text/html")
|> Plug.Conn.send_resp(200, html)
end
end
\ No newline at end of file
diff --git a/lib/open_api_spex/plug/validate.ex b/lib/open_api_spex/plug/validate.ex
index 65fded3..52fd2cf 100644
--- a/lib/open_api_spex/plug/validate.ex
+++ b/lib/open_api_spex/plug/validate.ex
@@ -1,26 +1,42 @@
defmodule OpenApiSpex.Plug.Validate do
+ @moduledoc """
+ Module plug that validates params against the schema defined for an operation.
+
+ If validation fails, the plug will send a 422 response with the reason as the body.
+ This plug should always be run after `OpenApiSpex.Plug.Cast`, as it expects the params map to
+ have atom keys and query params converted from strings to the appropriate types.
+
+ ## Example
+
+ defmodule MyApp.UserController do
+ use Phoenix.Controller
+ plug OpenApiSpex.Plug.Cast
+ plug OpenApiSpex.Plug.Validate
+ ...
+ end
+ """
@behaviour Plug
alias Plug.Conn
@impl Plug
def init(opts), do: opts
@impl Plug
def call(conn, _opts) do
spec = conn.private.open_api_spex.spec
operation_id = conn.private.open_api_spex.operation_id
operation_lookup = conn.private.open_api_spex.operation_lookup
operation = operation_lookup[operation_id]
content_type = Conn.get_req_header(conn, "content-type") |> Enum.at(0)
with :ok <- OpenApiSpex.validate(spec, operation, conn.params, content_type) do
conn
else
{:error, reason} ->
conn
|> Conn.send_resp(422, "#{reason}")
|> Conn.halt()
end
end
end
\ No newline at end of file
diff --git a/lib/open_api_spex/test/assertions.ex b/lib/open_api_spex/test/assertions.ex
index dfa2986..b2a4444 100644
--- a/lib/open_api_spex/test/assertions.ex
+++ b/lib/open_api_spex/test/assertions.ex
@@ -1,17 +1,25 @@
defmodule OpenApiSpex.Test.Assertions do
+ @moduledoc """
+ Defines helpers for testing API responses and examples against API spec schemas.
+ """
alias OpenApiSpex.OpenApi
import ExUnit.Assertions
@dialyzer {:no_match, assert_schema: 3}
+ @doc """
+ Asserts that `value` conforms to the schema with title `schema_title` in `api_spec`.
+ """
+ @spec assert_schema(map, String.t, OpenApi.t) :: :ok | no_return
def assert_schema(value = %{}, schema_title, api_spec = %OpenApi{}) do
schemas = api_spec.components.schemas
schema = schemas[schema_title]
if !schema do
flunk("Schema: #{schema_title} not found in #{inspect(Map.keys(schemas))}")
end
_ = assert {:ok, data} = OpenApiSpex.cast(api_spec, schema, value)
_ = assert :ok = OpenApiSpex.validate(api_spec, schema, data)
+ :ok
end
end
\ No newline at end of file

File Metadata

Mime Type
text/x-diff
Expires
Sat, Nov 23, 12:57 PM (1 d, 4 h)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
38978
Default Alt Text
(12 KB)

Event Timeline