Add YAML formatter #463

README.md

@@ -269,6 +269,7 @@ convenience, create a direct alias:
 
 ```shell
 mix openapi.spec.json --spec MyAppWeb.ApiSpec
+mix openapi.spec.yaml --spec MyAppWeb.ApiSpec
 ```
 
 ## Serve Swagger UI

lib/mix/tasks/openapi.spec.json.ex

@@ -23,83 +23,21 @@ defmodule Mix.Tasks.Openapi.Spec.Json do
 
   @default_filename "openapi.json"
 
-  defmodule Options do
-    @moduledoc false
-
-    defstruct filename: nil, spec: nil, pretty: false, vendor_extensions: true
-  end
-
   @impl true
   def run(argv) do
     Mix.Task.run("app.start")
-    opts = parse_options(argv)
-    content = generate_spec(opts)
-    write_spec(content, opts.filename)
+    OpenApiSpex.ExportSpec.call(argv, &encode/2, @default_filename)
   end
 
-  def generate_spec(%{spec: spec, pretty: pretty, vendor_extensions: vendor_extensions}) do
-    case Code.ensure_compiled(spec) do
-      {:module, _} ->
-        if function_exported?(spec, :spec, 0) do
-          json_encoder = OpenApiSpex.OpenApi.json_encoder()
-          spec = spec.spec()
-
-          json_encoding_result =
-            spec
-            |> OpenApiSpex.OpenApi.to_map(vendor_extensions: vendor_extensions)
-            |> json_encoder.encode(pretty: pretty)
-
-          case json_encoding_result do
-            {:ok, json} ->
-              json
-
-            {:error, error} ->
-              Mix.raise("could not encode #{inspect(spec)}, error: #{inspect(error)}.")
-          end
-        else
-          Mix.raise(
-            "module #{inspect(spec)} is not a OpenApiSpex.Spec. " <>
-              "Please pass a spec with the --spec option."
-          )
-        end
+  defp encode(spec, %{pretty: pretty}) do
+    spec
+    |> OpenApiSpex.OpenApi.json_encoder().encode(pretty: pretty)
+    |> case do
+      {:ok, json} ->
+        "#{json}\n"
 
       {:error, error} ->
-        Mix.raise(
-          "could not load #{inspect(spec)}, error: #{inspect(error)}. " <>
-            "Please pass a spec with the --spec option."
-        )
+        Mix.raise("could not encode #{inspect(spec)}, error: #{inspect(error)}.")
     end
   end
-
-  defp parse_options(argv) do
-    parse_options = [
-      strict: [spec: :string, endpoint: :string, pretty: :boolean, vendor_extensions: :boolean]
-    ]
-
-    {opts, args, _} = OptionParser.parse(argv, parse_options)
-
-    %Options{
-      filename: args |> List.first() || @default_filename,
-      spec: find_spec(opts),
-      pretty: Keyword.get(opts, :pretty, false),
-      vendor_extensions: Keyword.get(opts, :vendor_extensions, true)
-    }
-  end
-
-  defp find_spec(opts) do
-    if spec = Keyword.get(opts, :spec) do
-      Module.concat([spec])
-    else
-      Mix.raise("No spec available. Please pass a spec with the --spec option")
-    end
-  end
-
-  defp write_spec(content, filename) do
-    case Path.dirname(filename) do
-      "." -> true
-      dir -> Mix.Generator.create_directory(dir)
-    end
-
-    Mix.Generator.create_file(filename, content, force: true)
-  end
 end

lib/mix/tasks/openapi.spec.yaml.ex

@@ -0,0 +1,40 @@
+defmodule Mix.Tasks.Openapi.Spec.Yaml do
+  @moduledoc """
+  Serialize the given OpenApi spec module to a YAML file.
+
+  ## Examples
+
+      $ mix openapi.spec.yaml --spec PhoenixAppWeb.ApiSpec apispec.yaml
+      $ mix openapi.spec.yaml --spec PhoenixAppWeb.ApiSpec --vendor-extensions=false
+
+  ## Command line options
+
+  * `--spec` - The ApiSpec module from which to generate the OpenAPI YAML file
+
+  * `--vendor-extensions` - Whether to include open_api_spex OpenAPI vendor extensions
+    (defaults to true)
+
+  """
+  use Mix.Task
+  require Mix.Generator
+
+  @default_filename "openapi.yaml"
+
+  @impl Mix.Task
+  def run(argv) do
+    Mix.Task.run("app.start")
+    OpenApiSpex.ExportSpec.call(argv, &encode/2, @default_filename)
+  end
+
+  defp encode(spec, opts) do
+    spec
+    |> OpenApiSpex.OpenApi.yaml_encoder().encode(opts)
+    |> case do
+      {:ok, yaml} ->
+        yaml
+
+      {:error, error} ->
+        Mix.raise("could not encode #{inspect(spec)}, error: #{inspect(error)}.")
+    end
+  end
+end

lib/open_api_spex/export_spec.ex

@@ -0,0 +1,73 @@
+defmodule OpenApiSpex.ExportSpec do
+  @moduledoc """
+  Store spec in specified encoding
+  """
+  require Mix.Generator
+
+  defmodule Options do
+    @moduledoc false
+
+    defstruct filename: nil, spec: nil, pretty: false, vendor_extensions: true
+  end
+
+  def call(argv, encode_spec, default_filename) do
+    opts = parse_options(argv, default_filename)
+
+    opts
+    |> generate_spec()
+    |> encode_spec.(opts)
+    |> write_spec(opts.filename)
+  end
+
+  defp generate_spec(%{spec: spec, vendor_extensions: vendor_extensions}) do
+    case Code.ensure_compiled(spec) do
+      {:module, _} ->
+        if function_exported?(spec, :spec, 0) do
+          OpenApiSpex.OpenApi.to_map(spec.spec(), vendor_extensions: vendor_extensions)
+        else
+          Mix.raise(
+            "module #{inspect(spec)} is not a OpenApiSpex.Spec. " <>
+              "Please pass a spec with the --spec option."
+          )
+        end
+
+      {:error, error} ->
+        Mix.raise(
+          "could not load #{inspect(spec)}, error: #{inspect(error)}. " <>
+            "Please pass a spec with the --spec option."
+        )
+    end
+  end
+
+  defp parse_options(argv, default_filename) do
+    parse_options = [
+      strict: [spec: :string, endpoint: :string, pretty: :boolean, vendor_extensions: :boolean]
+    ]
+
+    {opts, args, _} = OptionParser.parse(argv, parse_options)
+
+    %Options{
+      filename: args |> List.first() || default_filename,
+      spec: find_spec(opts),
+      pretty: Keyword.get(opts, :pretty, false),
+      vendor_extensions: Keyword.get(opts, :vendor_extensions, true)
+    }
+  end
+
+  defp write_spec(content, filename) do
+    case Path.dirname(filename) do
+      "." -> true
+      dir -> Mix.Generator.create_directory(dir)
+    end
+
+    Mix.Generator.create_file(filename, content, force: true)
+  end
+
+  defp find_spec(opts) do
+    if spec = Keyword.get(opts, :spec) do
+      Module.concat([spec])
+    else
+      Mix.raise("No spec available. Please pass a spec with the --spec option")
+    end
+  end
+end

lib/open_api_spex/open_api.ex

@@ -91,6 +91,22 @@ defmodule OpenApiSpex.OpenApi do
     end
   end
 
+  if Code.ensure_loaded?(Ymlr) do
+    defmodule YmlrEncoder do
+      @moduledoc false
+
+      def encode(api_spec = %{}, _options) do
+        api_spec
+        |> OpenApi.to_map()
+        |> Ymlr.document()
+      end
+    end
+
+    @yaml_encoder YmlrEncoder
+  end
+
+  def yaml_encoder, do: @yaml_encoder
+
   def to_map(value), do: to_map(value, [])
   def to_map(%Regex{source: source}, _opts), do: source
 

mix.exs

@@ -61,7 +61,8 @@ defmodule OpenApiSpex.Mixfile do
       {:jason, "~> 1.0", optional: true},
       {:phoenix, "~> 1.3", only: [:dev, :test]},
       {:plug, "~> 1.7"},
-      {:poison, "~> 4.0 or ~> 5.0", optional: true}
+      {:poison, "~> 4.0 or ~> 5.0", optional: true},
+      {:ymlr, "~> 2.0", optional: true}
     ]
   end
 

mix.lock

@@ -19,4 +19,5 @@
   "plug_crypto": {:hex, :plug_crypto, "1.2.2", "05654514ac717ff3a1843204b424477d9e60c143406aa94daf2274fdd280794d", [:mix], [], "hexpm", "87631c7ad914a5a445f0a3809f99b079113ae4ed4b867348dd9eec288cecb6db"},
   "poison": {:hex, :poison, "5.0.0", "d2b54589ab4157bbb82ec2050757779bfed724463a544b6e20d79855a9e43b24", [:mix], [{:decimal, "~> 2.0", [hex: :decimal, repo: "hexpm", optional: true]}], "hexpm", "11dc6117c501b80c62a7594f941d043982a1bd05a1184280c0d9166eb4d8d3fc"},
   "telemetry": {:hex, :telemetry, "1.0.0", "0f453a102cdf13d506b7c0ab158324c337c41f1cc7548f0bc0e130bbf0ae9452", [:rebar3], [], "hexpm", "73bc09fa59b4a0284efb4624335583c528e07ec9ae76aca96ea0673850aec57a"},
+  "ymlr": {:hex, :ymlr, "2.0.0", "7525b6da40250777c35456017ef44f7faec06da254eafcf9f9cfb0d65f4c8cb7", [:mix], [], "hexpm", "f9301ad7ea377213b506f6e58ddffd1a7743e24238bb70e572ee510bdc2d1d5a"},
 }

test/mix/tasks/openapi.spec.json_test.exs

@@ -0,0 +1,21 @@
+defmodule Mix.Tasks.Openapi.Spec.JsonTest do
+  use ExUnit.Case
+
+  test "generates openapi.json" do
+    actual_schema_path = "tmp/openapi.json"
+
+    Mix.Tasks.Openapi.Spec.Json.run(~w(
+      --pretty=true
+      --spec OpenApiSpexTest.Tasks.SpecModule
+      --vendor-extensions=false
+      #{actual_schema_path}
+    ))
+
+    expected_schema_path = "test/support/tasks/openapi.json"
+
+    assert_received {:mix_shell, :info, ["* creating tmp"]}
+    assert_received {:mix_shell, :info, ["* creating tmp/openapi.json"]}
+
+    assert File.read!(actual_schema_path) == File.read!(expected_schema_path)
+  end
+end

test/mix/tasks/openapi.spec.yaml_test.exs

@@ -0,0 +1,20 @@
+defmodule Mix.Tasks.Openapi.Spec.YamlTest do
+  use ExUnit.Case
+
+  test "generates openapi.yaml" do
+    actual_schema_path = "tmp/openapi.yaml"
+
+    Mix.Tasks.Openapi.Spec.Yaml.run(~w(
+      --spec OpenApiSpexTest.Tasks.SpecModule
+      --vendor-extensions=false
+      #{actual_schema_path}
+    ))
+
+    expected_schema_path = "test/support/tasks/openapi.yaml"
+
+    assert_received {:mix_shell, :info, ["* creating tmp"]}
+    assert_received {:mix_shell, :info, ["* creating tmp/openapi.yaml"]}
+
+    assert File.read!(actual_schema_path) == File.read!(expected_schema_path)
+  end
+end

test/support/tasks/openapi.json

@@ -0,0 +1,35 @@
+{
+  "info": {
+    "title": "Test spec",
+    "version": "1.0"
+  },
+  "openapi": "3.0.0",
+  "paths": {
+    "/users": {
+      "post": {
+        "callbacks": {},
+        "deprecated": false,
+        "operationId": "users.create",
+        "parameters": [],
+        "responses": {},
+        "tags": []
+      },
+      "put": {
+        "callbacks": {},
+        "deprecated": false,
+        "operationId": "users.update",
+        "parameters": [],
+        "responses": {},
+        "tags": []
+      }
+    }
+  },
+  "security": [],
+  "servers": [
+    {
+      "url": "http://localhost:4000",
+      "variables": {}
+    }
+  ],
+  "tags": []
+}

test/support/tasks/openapi.yaml

@@ -0,0 +1,26 @@
+---
+info:
+  title: Test spec
+  version: '1.0'
+openapi: 3.0.0
+paths:
+  /users:
+    post:
+      callbacks: {}
+      deprecated: false
+      operationId: users.create
+      parameters: []
+      responses: {}
+      tags: []
+    put:
+      callbacks: {}
+      deprecated: false
+      operationId: users.update
+      parameters: []
+      responses: {}
+      tags: []
+security: []
+servers:
+  - url: http://localhost:4000
+    variables: {}
+tags: []

test/support/tasks/spec_module.ex

@@ -0,0 +1,24 @@
+defmodule OpenApiSpexTest.Tasks.SpecModule do
+  alias OpenApiSpex.{Info, OpenApi, Operation, Server}
+
+  @behaviour OpenApi
+
+  @impl OpenApi
+  def spec do
+    %OpenApi{
+      info: %Info{
+        title: "Test spec",
+        version: "1.0"
+      },
+      paths: %{
+        "/users" => %{
+          "post" => %Operation{operationId: "users.create", responses: %{}},
+          "put" => %Operation{operationId: "users.update", responses: %{}}
+        }
+      },
+      servers: [
+        %Server{url: "http://localhost:4000"}
+      ]
+    }
+  end
+end

test/test_helper.exs

@@ -1 +1,2 @@
+Mix.shell(Mix.Shell.Process)
 ExUnit.start(exclude: [:skip])