qarma-inspect/jungle-spec

JungleSpec

A library providing simplified and less verbose way of definining OpenApiSpex types.

Example definition:

defmodule Employee do
  use JungleSpec

  open_api_object "Employee", extends: Person, struct?: false do
    property :level, :string, enum: ["L1", "L2", "L3"]
    property :experience, [:number, :string]
    property :is_manager, :boolean, default: false
    property :team_members, {:array, Employee}, nullable: true
    property :technologies_to_experience, {:map, :string}
    additional_properties :integer
  end
end

It creates an OpenApiSpex type with title "Employee" that has all properties from the schema defined in Person module. It also won't create any struct corresponding to the Employee module.

Other properties in the Employee schema:

• :level - it has type :string and can be one of ["L1", "L2", "L3"]
• :experience - its type is a union of :number and :string
• :is_manager - it has type :boolean and is false by default
• :team_members - its type is an array with employees or nil
• :technologies_to_experience - its type is an object with additional properties having type :string
• additional_properties - the schema can have more properties having type :integer

All properties are required and not nullable by default.

Also, the following typespec will be created:

@type t :: %{
  # additional properties
  String.t() => integer(),
  # properties
  level: String.t(),
  experience: number() | String.t(),
  is_manager: boolean(),
  team_members: [t()] | nil,
  technologies_to_experience: %{optional(String.t()) => String.t()},
  ... # and all properties from Person
}

For more information refer to JungleSpec module docs.

jungle-spec's Issues

additional_property macro should support external types and arrays

Thanks a lot for the amazing library!

Currently additional_property macro doesn't support complex (schema-based) types and arrays.

So the following would not work:

defmodule MyAppWeb.Schemas.UUID do
  use JungleSpec

  @title "UUID"

  open_api_type @title, :string,
    nullable: true,
    format: :uuid,
    pattern: ~r/[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}/,
    example: "193202fc-ab55-4824-8ec8-5bef1201d9eb"
end

### the following will produce errors

defmodule MyAppWeb.Schemas.MapWithExternalType do
  use JungleSpec

  @title "MapWithExternalType",
  @description: "Map With External Type"

  alias MyAppWeb.Schemas.UUID

  open_api_object @title, description: @description, struct?: false do
    additional_properties UUID
  end

end

defmodule MyAppWeb.Schemas.MapWithExternalTypeList do
  use JungleSpec

  @title "MapWithExternalTypeList",
  @description: "Map With External Type List"

  alias MyAppWeb.Schemas.UUID

  open_api_object @title, description: @description, struct?: false do
    additional_properties {:array, UUID}
  end

end

Feature: add additional object property type to describe dictionaries/maps in a more convenient way

I just realize that quite often we need to have fields which are effectively just maps/dictionaries, like %{String.t() => OtherDataType.t()}. As properties can't have nested object description (which is good I think) currently we have to introduce additional modules to include maps:

defmodule MyAppWeb.Schemas.UUID do
  use JungleSpec

  @title "UUID"

  open_api_type @title, :string,
    nullable: true,
    format: :uuid,
    pattern: ~r/[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}/,
    example: "193202fc-ab55-4824-8ec8-5bef1201d9eb"
end

defmodule MyAppWeb.Schemas.MapWithExternalType do
  use JungleSpec

  @title "MapWithExternalType",
  @description: "Map With External Type"

  alias MyAppWeb.Schemas.UUID

  open_api_object @title, description: @description, struct?: false do
    additional_properties UUID
  end

end

defmodule MyAppWeb.Schemas.MapWithExternalTypeList do
  use JungleSpec

  @title "MapWithExternalTypeList",
  @description: "Map With External Type List"

  alias MyAppWeb.Schemas.UUID

  open_api_object @title, description: @description, struct?: false do
    additional_properties {:array, UUID}
  end

end

defmodule MyAppWeb.Schemas.ComplexResponse do

  use JungleSpec

  @title "ComplexResponse",
  @description: "Complex Response Schema"

  alias MyAppWeb.Schemas

  open_api_object @title, description: @description, do
    property :key_to_single_item_map, Schemas.MapWithExternalType
    property :key_to_list_map, Schemas.MapWithExternalTypeList
  end
end

which is quite complex and redundant.

Probably it will be easier to use something like

defmodule MyAppWeb.Schemas.UUID do
  use JungleSpec

  @title "UUID"

  open_api_type @title, :string,
    nullable: true,
    format: :uuid,
    pattern: ~r/[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}/,
    example: "193202fc-ab55-4824-8ec8-5bef1201d9eb"
end

defmodule MyAppWeb.Schemas.ComplexResponse do

  use JungleSpec

  @title "ComplexResponse",
  @description: "Complex Response Schema"

  MyAppWeb.Schemas.UUID

  open_api_object @title, description: @description, do
    property :simple_one_to_one_map, {:map, UUID}
    property :key_to_list_map, {:map, {:array, UUID}}
  end
end

or we can use more "readable" way as:

  open_api_object @title, description: @description, do
    property :simple_one_to_one_map, :map, items: UUID
    property :key_to_list_map, :map, items: {:array, UUID}
  end

Also may be :map type isn't suit in full so we can use other atom like :dict or whatever.