Open Api Specifications

Author: mbuhot

.gitignore

@@ -0,0 +1,20 @@
+# The directory Mix will write compiled artifacts to.
+/_build/
+
+# If you run "mix test --cover", coverage assets end up here.
+/cover/
+
+# The directory Mix downloads your dependencies sources to.
+/deps/
+
+# Where 3rd-party dependencies like ExDoc output generated docs.
+/doc/
+
+# Ignore .fetch files in case you like to edit your project deps locally.
+/.fetch
+
+# If the VM crashes, it generates a dump, let's ignore it too.
+erl_crash.dump
+
+# Also ignore archive artifacts (built via "mix archive.build").
+*.ez

LICENSE

@@ -0,0 +1,149 @@
+# Open API Spex
+
+Add Open API Specification 3 (formerly swagger) to Plug applications.
+
+## Installation
+
+The package can be installed by adding `open_api_spex` to your list of dependencies in `mix.exs`:
+
+```elixir
+def deps do
+  [
+    {:open_api_spex, github: "mbuhot/open_api_spex"}
+  ]
+end
+```
+
+## Usage
+
+Start by adding an `ApiSpec` module to your application.
+
+```elixir
+defmodule MyApp.ApiSpec do
+  alias OpenApiSpex.{OpenApi, Server, Info, Paths}
+
+  def spec do
+    %OpenApi{
+      servers: [
+        # Populate the Server info from a phoenix endpoint
+        Server.from_endpoint(MyAppWeb.Endpoint, otp_app: :my_app)
+      ],
+      info: %Info{
+        title: "My App",
+        version: "1.0"
+      },
+      # populate the paths from a phoenix router
+      paths: Paths.from_router(MyAppWeb.Router)
+    }
+    |> OpenApiSpex.resolve_schema_modules() # discover request/response schemas from path specs
+  end
+end
+```
+
+For each plug (controller) that will handle api requests, add an `open_api_operation` callback.
+It will be passed the plug opts that were declared in the router, this will be the action for a phoenix controller.
+
+```elixir
+defmodule MyApp.UserController do
+  alias OpenApiSpex.Operation
+
+  @spec open_api_operation(any) :: 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", Schemas.UserResponse)
+      }
+    }
+  end
+  def show(conn, %{"id" => id}) do
+    {:ok, user} = MyApp.Users.find_by_id(id)
+    json(conn, 200, user)
+  end
+end
+```
+
+Declare the JSON schemas for request/response bodies in a `Schemas` module:
+
+```elixir
+defmodule MyApp.Schemas do
+  alias OpenApiSpex.Schema
+
+  defmodule User do
+    def schema do
+      %Schema{
+        title: "User",
+        description: "A user of the app",
+        type: :object,
+        properties: %{
+          id: %Schema{type: :integer, description: "User ID"},
+          name:  %Schema{type: :string, description: "User name"},
+          email: %Schema{type: :string, description: "Email address", format: :email},
+          inserted_at: %Schema{type: :string, description: "Creation timestamp", format: :datetime},
+          updated_at: %Schema{type: :string, description: "Update timestamp", format: :datetime}
+        }
+      }
+    end
+  end
+
+  defmodule UserResponse do
+    def schema do
+      %Schema{
+        title: "UserResponse",
+        description: "Response schema for single user",
+        type: :object,
+        properties: %{
+          data: User
+        }
+      }
+    end
+  end
+end
+```
+
+Now you can create a mix task to write the swagger file to disk:
+
+```elixir
+defmodule Mix.Tasks.MyApp.OpenApiSpec do
+  def run([output_file]) do
+    json =
+      MyApp.ApiSpec.spec()
+      |> Poison.encode!(pretty: true)
+
+    :ok = File.write!(output_file, json)
+  end
+end
+```
+
+Generate the file with: `mix myapp.openapispec spec.json`
+
+You can also serve the swagger through a controller:
+
+```elixir
+defmodule MyApp.OpenApiSpecController do
+  def show(conn, _params) do
+    spec =
+      MyApp.ApiSpec.spec()
+
+    json(conn, spec)
+  end
+end
+```
+
+TODO: SwaggerUI 3.0
+
+TODO: Request Validation
+
+TODO: Validating examples in the spec
+
+TODO: Validating responses in tests

README.md

@@ -0,0 +1,30 @@
+# This file is responsible for configuring your application
+# and its dependencies with the aid of the Mix.Config module.
+use Mix.Config
+
+# This configuration is loaded before any dependency and is restricted
+# to this project. If another project depends on this project, this
+# file won't be loaded nor affect the parent project. For this reason,
+# if you want to provide default values for your application for
+# 3rd-party users, it should be done in your "mix.exs" file.
+
+# You can configure your application as:
+#
+#     config :open_api_spex, key: :value
+#
+# and access this configuration in your application as:
+#
+#     Application.get_env(:open_api_spex, :key)
+#
+# You can also configure a 3rd-party app:
+#
+#     config :logger, level: :info
+#
+
+# It is also possible to import configuration files, relative to this
+# directory. For example, you can emulate configuration per environment
+# by uncommenting the line below and defining dev.exs, test.exs and such.
+# Configuration from the imported file will override the ones defined
+# here (which is why it is important to import them last).
+#
+#     import_config "#{Mix.env}.exs"

config/config.exs

@@ -0,0 +1,11 @@
+defmodule OpenApiSpex do
+  alias OpenApiSpex.{OpenApi, SchemaResolver}
+
+  @moduledoc """
+  """
+  def resolve_schema_modules(spec = %OpenApi{}) do
+    SchemaResolver.resolve_schema_modules(spec)
+  end
+
+
+end

lib/open_api_spex.ex

@@ -0,0 +1,6 @@
+defmodule OpenApiSpex.Callback do
+  alias OpenApiSpex.PathItem
+  @type t :: %{
+    String.t => PathItem.t
+  }
+end

lib/open_api_spex/callback.ex

@@ -0,0 +1,28 @@
+defmodule OpenApiSpex.Components do
+  alias OpenApiSpex.{
+    Schema, Reference, Response, Parameter, Example,
+    RequestBody, Header, SecurityScheme, Link, Callback
+  }
+  defstruct [
+    :schemas,
+    :responses,
+    :parameters,
+    :examples,
+    :requestBodies,
+    :headers,
+    :securitySchemes,
+    :links,
+    :callbacks,
+  ]
+  @type t :: %{
+    schemas: %{String.t => Schema.t | Reference.t},
+    responses: %{String.t =>  Response.t | Reference.t},
+    parameters: %{String.t =>  Parameter.t | Reference.t},
+    examples: %{String.t => Example.t | Reference.t},
+    requestBodies: %{String.t => RequestBody.t | Reference.t},
+    headers: %{String.t =>  Header.t | Reference.t},
+    securitySchemes: %{String.t =>  SecurityScheme.t | Reference.t},
+    links: %{String.t => Link.t | Reference.t},
+    callbacks: %{String.t => Callback.t | Reference.t}
+  }
+end

lib/open_api_spex/components.ex

@@ -0,0 +1,12 @@
+defmodule OpenApiSpex.Contact do
+  defstruct [
+    :name,
+    :url,
+    :email
+  ]
+  @type t :: %__MODULE__{
+    name: String.t,
+    url: String.t,
+    email: String.t
+  }
+end

lib/open_api_spex/contact.ex

@@ -0,0 +1,10 @@
+defmodule OpenApiSpex.Discriminator do
+  defstruct [
+    :propertyName,
+    :mapping
+  ]
+  @type t :: %__MODULE__{
+    propertyName: String.t,
+    mapping: %{String.t => String.t}
+  }
+end

lib/open_api_spex/discriminator.ex

@@ -0,0 +1,17 @@
+defmodule OpenApiSpex.Encoding do
+  alias OpenApiSpex.{Header, Reference, Parameter}
+  defstruct [
+    :contentType,
+    :headers,
+    :style,
+    :explode,
+    :allowReserved
+  ]
+  @type t :: %__MODULE__{
+    contentType: String.t,
+    headers: %{String.t => Header.t | Reference.t},
+    style: Parameter.style,
+    explode: boolean,
+    allowReserved: boolean
+  }
+end

lib/open_api_spex/encoding.ex

@@ -0,0 +1,14 @@
+defmodule OpenApiSpex.Example do
+  defstruct [
+    :summary,
+    :description,
+    :value,
+    :externalValue
+  ]
+  @type t :: %{
+    summary: String.t,
+    description: String.t,
+    value: any,
+    externalValue: String.t
+  }
+end

lib/open_api_spex/example.ex

@@ -0,0 +1,10 @@
+defmodule OpenApiSpex.ExternalDocumentation do
+  defstruct [
+    :description,
+    :url
+  ]
+  @type t :: %__MODULE__{
+    description: String.t,
+    url: String.t
+  }
+end

lib/open_api_spex/external_documentation.ex

@@ -0,0 +1,25 @@
+defmodule OpenApiSpex.Header do
+  alias OpenApiSpex.{Schema, Reference, Example}
+  defstruct [
+    :description,
+    :required,
+    :deprecated,
+    :allowEmptyValue,
+    :explode,
+    :schema,
+    :example,
+    :examples,
+    style: :simple
+  ]
+  @type t :: %__MODULE__{
+    description: String.t,
+    required: boolean,
+    deprecated: boolean,
+    allowEmptyValue: boolean,
+    style: :simple,
+    explode: boolean,
+    schema: Schema.t | Reference.t,
+    example: any,
+    examples: %{String.t => Example.t | Reference.t}
+  }
+end

lib/open_api_spex/header.ex

@@ -0,0 +1,20 @@
+defmodule OpenApiSpex.Info do
+  alias OpenApiSpex.{Contact, License}
+  @enforce_keys [:title, :version]
+  defstruct [
+    :title,
+    :description,
+    :termsOfService,
+    :contact,
+    :license,
+    :version
+  ]
+  @type t :: %__MODULE__{
+    title: String.t,
+    description: String.t,
+    termsOfService: String.t,
+    contact: Contact.t,
+    license: License.t,
+    version: String.t
+  }
+end

lib/open_api_spex/info.ex

@@ -0,0 +1,10 @@
+defmodule OpenApiSpex.License do
+  defstruct [
+    :name,
+    :url
+  ]
+  @type t :: %__MODULE__{
+    name: String.t,
+    url: String.t
+  }
+end