Similar to Ecto.Schema, define Schema of Open Api Spec as DSL syntax.

schema macro

To define schema, use schema/2 macro. It must be used once in a module.

schema/2 macro define a function named schema/0, which return a %OpenApiSpex.Schema{} struct. The first argument of schema/2 macro is required and it become :title field of the struct.

Example

defmodule SimpleUser do
  use OpenApiSpex.Schemax

  @required [:id, :name]
  schema "SimpleUser" do
    property :id, :integer
    property :name, :string
    property :is_verified, :boolean
  end
endcopy

when you call the created function schema/0, it will show:

iex> SimpleUser.schema()
%OpenApiSpex.Schema{
  title: "SimpleUser",
  type: :object,
  properties: %{id: %OpenApiSpex.Schema{type: :integer},
  name: %OpenApiSpex.Schema{type: :string},
  is_verified: %OpenApiSpex.Schema{type: :boolean}},
  required: [:id, :name]
}copy

embedded_schema/2 macro

Unlike schema/2, embedded_schema/2 macro can be defined multiple time in a module. Sometimes when you have deep nested schema, it is bothering that turn every schema into modules. In that case, you might want to temporary schemas in a module, which you can do through this macro. When you define this macro, unlike schema macro, put function name into first argument of macro instead of title. After that, when you want to use that embedded schema, call that function name.

define both of :schema_type and :required fields are also included in do block, unlike schema macro which defines them as module attributes.

Example

defmodule ListResponse do
  use OpenApiSpex.Schemax

  schema "ListResponse" do
    property :list, list()
  end

  embedded_schema :list do
    property :id, :integer
    property :name, :string
    required [:id, :name]
  end
endcopy