Release: v0.7.1

lib/mix/tasks/rolodex.gen.docs.ex

@@ -20,7 +20,9 @@ defmodule Mix.Tasks.Rolodex.Gen.Docs do
       {:error, err}, acc -> [err | acc]
     end)
     |> case do
-      [] -> IO.puts("Done!")
+      [] ->
+        IO.puts("Done!")
+
       errs ->
         IO.puts("Rolodex failed to compile some docs with the following errors:")
         Enum.each(errs, &IO.inspect(&1))

lib/rolodex.ex

@@ -28,7 +28,7 @@ defmodule Rolodex do
   annotations on your API route action functions for the Rolodex parser to handle
   - **Generic serialization** - The `Rolodex.Processor` behaviour encapsulates
   the basic steps needed to serialize API metadata into documentation. Rolodex
-  ships with a valid Swagger JSON processor (see: `Rolodex.Processors.Swagger`)
+  ships with a valid OpenAPI (Swagger) JSON processor (see: `Rolodex.Processors.OpenAPI`)
   - **Generic writing** - The `Rolodex.Writer` behaviour encapsulates the basic
   steps needed to write out formatted docs. Rolodex ships with a file writer (
   see: `Rolodex.Writers.FileWriter`)

lib/rolodex/config.ex

@@ -50,7 +50,7 @@ defmodule Rolodex.Config do
   - `locale` (default: `"en"`) - Locale key to use when processing descriptions
   - `pipelines` (default: `%{}`) - Map of pipeline configs. Used to set default
   parameter values for all routes in a pipeline. See `Rolodex.PipelineConfig`.
-  - `render_groups` (default: `%Rolodex.RenderGroupConfig{}`) - List of render
+  - `render_groups` (default: `Rolodex.RenderGroupConfig`) - List of render
   groups.
   - `server_urls` (default: []) - List of base url(s) for your API paths
 
@@ -215,7 +215,7 @@ defmodule Rolodex.RenderGroupConfig do
   out routes from your documentation. Filters are invoked in
   `Rolodex.Route.matches_filter?/2`. If the match returns true, the route will be
   filtered out of the docs result for this render group.
-  - `processor` (default: `Rolodex.Processors.Swagger`) - Module implementing
+  - `processor` (default: `Rolodex.Processors.OpenAPI`) - Module implementing
   the `Rolodex.Processor` behaviour
   - `writer` (default: `Rolodex.Writers.FileWriter`) - Module implementing the
   `Rolodex.Writer` behaviour to be used to write out the docs
@@ -224,7 +224,7 @@ defmodule Rolodex.RenderGroupConfig do
   """
 
   defstruct filters: :none,
-            processor: Rolodex.Processors.Swagger,
+            processor: Rolodex.Processors.OpenAPI,
             writer: Rolodex.Writers.FileWriter,
             writer_opts: [file_name: "api.json"]
 

lib/rolodex/content_utils.ex

@@ -89,6 +89,16 @@ defmodule Rolodex.ContentUtils do
     end
   end
 
+  def set_field(attr, identifier, list_items, _opts) when is_list(list_items) do
+    quote do
+      Module.put_attribute(
+        __MODULE__,
+        unquote(attr),
+        {unquote(identifier), [type: :list, of: unquote(list_items)]}
+      )
+    end
+  end
+
   def set_field(attr, identifier, type, opts) do
     quote do
       Module.put_attribute(

lib/rolodex/field.ex

@@ -26,7 +26,7 @@ defmodule Rolodex.Field do
 
   ## Examples
 
-  ### Parsing primitive data types (e.g. `string`)
+  ### Parsing primitive data types (e.g. `integer`)
 
   Valid options for a primitive are:
 
@@ -39,12 +39,36 @@ defmodule Rolodex.Field do
   - `required`
 
       # Creating a simple field with a primitive type
-      iex> Rolodex.Field.new(:string)
-      %{type: :string}
+      iex> Rolodex.Field.new(:integer)
+      %{type: :integer}
 
       # With additional options
-      iex> Rolodex.Field.new(type: :string, desc: "My string", enum: ["foo", "bar"])
-      %{type: :string, desc: "My string", enum: ["foo", "bar"]}
+      iex> Rolodex.Field.new(type: :integer, desc: "My count", enum: [1, 2])
+      %{type: :integer, desc: "My count", enum: [1, 2]}
+
+  ### OpenAPI string formats
+
+  When serializing docs for OpenAPI (i.e. Swagger), the following primitive field
+  types will be converted into string formats:
+
+  - `date`
+  - `datetime`
+  - `date-time`
+  - `password`
+  - `byte`
+  - `binary`
+  - `uuid`
+  - `email`
+  - `uri`
+
+  For example:
+
+      # The following field
+      iex> Rolodex.Field.new(:date)
+      %{type: :date}
+
+      # Will be serialized like the following for OpenAPI docs
+      %{type: :string, format: :date}
 
   ### Parsing collections: objects and lists
 

lib/rolodex/processors/swagger.ex → lib/rolodex/processors/open_api.ex

@@ -1,15 +1,26 @@
-defmodule Rolodex.Processors.Swagger do
+defmodule Rolodex.Processors.OpenAPI do
   @behaviour Rolodex.Processor
   @open_api_version "3.0.0"
 
-  @schema_metadata_keys [
-    :default,
-    :enum,
-    :format,
-    :maximum,
-    :minimum,
-    :type
-  ]
+  @schema_metadata_keys ~w(
+    default
+    enum
+    format
+    maximum
+    minimum
+    type
+  )a
+
+  @valid_string_formats ~w(
+    date
+    date-time
+    password
+    byte
+    binary
+    uuid
+    email
+    uri
+  )a
 
   alias Rolodex.{Config, Field, Headers, Route}
 
@@ -259,9 +270,16 @@ defmodule Rolodex.Processors.Swagger do
     }
   end
 
-  defp process_schema_field(%{type: :uuid} = field) do
+  defp process_schema_field(%{type: type} = field) when type in @valid_string_formats do
     field
-    |> Map.merge(%{type: :string, format: :uuid})
+    |> set_formatted_string_field(type)
+    |> process_schema_field()
+  end
+
+  # Also support datetime as a single word b/c the dash is weird especially in an atom
+  defp process_schema_field(%{type: :datetime} = field) do
+    field
+    |> set_formatted_string_field(:"date-time")
     |> process_schema_field()
   end
 
@@ -297,6 +315,12 @@ defmodule Rolodex.Processors.Swagger do
 
   defp set_param_description(param), do: param
 
+  defp set_formatted_string_field(field, format) do
+    field
+    |> Map.put(:type, :string)
+    |> Map.put(:format, format)
+  end
+
   defp ref_path(mod) do
     case Field.get_ref_type(mod) do
       :request_body -> "#/components/requestBodies/#{mod.__request_body__(:name)}"

lib/rolodex/schema.ex

@@ -76,6 +76,8 @@ defmodule Rolodex.Schema do
   one argument is the field `identifier`. This can be used to fetch the field
   metadata later.
 
+  See `Rolodex.Field` for more information about valid field metadata.
+
   Accepts
   - `identifier` - field name
   - `type` - either an atom or another Rolodex.Schema module
@@ -99,6 +101,10 @@ defmodule Rolodex.Schema do
           # A field that is an array of items of one-or-more types
           field :multi, :list, of: [:string, OtherSchema]
 
+          # You can use a shorthand to define a list field, the below is identical
+          # to the above
+          field :multi, [:string, OtherSchema]
+
           # A field that is one of the possible provided types
           field :any, :one_of, of: [:string, OtherSchema]
         end

mix.exs

@@ -6,7 +6,7 @@ defmodule Rolodex.MixProject do
       app: :rolodex,
       name: "Rolodex",
       description: "Automated docs generation",
-      version: "0.7.0",
+      version: "0.7.1",
       elixir: "~> 1.7",
       elixirc_paths: elixirc_paths(Mix.env()),
       start_permanent: Mix.env() == :prod,