WIP json:api helpers

lib/open_api_spex/json_api_helpers.ex

@@ -0,0 +1,39 @@
+defmodule OpenApiSpex.JsonApiHelpers do
+  alias OpenApiSpex.JsonApiHelpers.{JsonApiDocument, JsonApiResource}
+
+  def document_schema(document) do
+    JsonApiDocument.schema(document)
+  end
+
+  def resource_schema(resource) do
+    JsonApiResource.schema(resource)
+  end
+
+  defmacro generate_document_schema(attrs) do
+    quote do
+      require OpenApiSpex
+
+      @document struct!(JsonApiDocument, unquote(attrs))
+      def document, do: @document
+
+      @document_schema JsonApiDocument.schema(@document)
+      def document_schema, do: @document_schema
+
+      OpenApiSpex.schema(@document_schema)
+    end
+  end
+
+  defmacro generate_resource_schema(attrs) do
+    quote do
+      require OpenApiSpex
+
+      @resource struct!(JsonApiResource, unquote(attrs))
+      def resource, do: @resource
+
+      @resource_schema JsonApiResource.schema(@resource)
+      def resource_schema, do: @resource_schema
+
+      OpenApiSpex.schema(@resource_schema)
+    end
+  end
+end

lib/open_api_spex/json_api_helpers/json_api_document.ex

@@ -0,0 +1,51 @@
+defmodule OpenApiSpex.JsonApiHelpers.JsonApiDocument do
+  alias OpenApiSpex.Schema
+  alias OpenApiSpex.JsonApiHelpers.JsonApiResource
+
+  defstruct resource: nil,
+            multiple: false,
+            title: nil,
+            "x-struct": nil
+
+  def schema(%__MODULE__{} = document) do
+    if not is_binary(document.title) do
+      raise "%JsonApiDocument{} :title is required and must be a string"
+    end
+
+    resource = document.resource
+    resource_item_schema = JsonApiResource.schema(resource)
+
+    resource_title =
+      case resource_item_schema do
+        %Schema{} = schema -> schema.title
+        module when is_atom(module) and not is_nil(module) -> module.schema().title
+      end
+
+    resource_schema =
+      if document.multiple do
+        %Schema{
+          type: :array,
+          items: resource_item_schema,
+          title: resource_title <> "List"
+        }
+      else
+        resource_item_schema
+      end
+
+    %Schema{
+      type: :object,
+      properties: %{
+        data: resource_schema
+      },
+      required: [:data],
+      title: document.title,
+      "x-struct": document."x-struct"
+    }
+  end
+
+  def schema(document_attrs) when is_list(document_attrs) or is_map(document_attrs) do
+    __MODULE__
+    |> struct!(document_attrs)
+    |> schema()
+  end
+end

lib/open_api_spex/json_api_helpers/json_api_resource.ex

@@ -0,0 +1,41 @@
+defmodule OpenApiSpex.JsonApiHelpers.JsonApiResource do
+  alias OpenApiSpex.Schema
+
+  defstruct additionalProperties: nil,
+            properties: %{},
+            required: [],
+            title: nil
+
+  def schema(resource) when is_atom(resource) and not is_nil(resource) do
+    resource.schema()."x-struct"
+  end
+
+  def schema(%__MODULE__{} = resource) do
+    if not is_binary(resource.title) do
+      raise "%JsonApiResource{} :title is required and must be a string"
+    end
+
+    %Schema{
+      type: :object,
+      properties: %{
+        id: %Schema{type: :string},
+        type: %Schema{type: :string},
+        attributes: attributes_schema(resource)
+      },
+      required: [:id, :type],
+      title: resource.title <> "Resource"
+    }
+  end
+
+  def attributes_schema(%__MODULE__{} = resource) do
+    if not is_binary(resource.title) do
+      raise "%JsonApiResource{} :title is required and must be a string"
+    end
+
+    %Schema{
+      type: :object,
+      properties: resource.properties,
+      title: resource.title <> "Attributes"
+    }
+  end
+end

lib/open_api_spex/schema_resolver.ex

@@ -37,7 +37,7 @@ defmodule OpenApiSpex.SchemaResolver do
     {paths, schemas} = resolve_schema_modules_from_paths(spec.paths, schemas)
     schemas = resolve_schema_modules_from_schemas(schemas)
     {responses, _} = resolve_schema_modules_from_responses(responses, schemas)
-    %{spec | paths: paths, components: %{components| schemas: schemas, responses: responses}}
+    %{spec | paths: paths, components: %{components | schemas: schemas, responses: responses}}
   end
 
   defp resolve_schema_modules_from_paths(paths = %{}, schemas = %{}) do
@@ -217,6 +217,13 @@ defmodule OpenApiSpex.SchemaResolver do
         properties: properties
     }
 
+    schemas =
+      if schema."x-struct" do
+        Map.put(schemas, schema.title, schema)
+      else
+        schemas
+      end
+
     {schema, schemas}
   end
 

test/controller_test.exs

@@ -65,14 +65,14 @@ defmodule OpenApiSpex.ControllerTest do
 
     test "has no docs when false" do
       assert capture_io(:stderr, fn ->
-        refute @controller.open_api_operation(:skip_this_doc)
-      end) == ""
+               refute @controller.open_api_operation(:skip_this_doc)
+             end) == ""
     end
 
     test "prints warn when no @doc specified" do
       assert capture_io(:stderr, fn ->
-        refute @controller.open_api_operation(:no_doc_specified)
-      end) =~ ~r/warning:/
+               refute @controller.open_api_operation(:no_doc_specified)
+             end) =~ ~r/warning:/
     end
   end
 
@@ -96,7 +96,7 @@ defmodule OpenApiSpex.ControllerTest do
     end
 
     test "fails on both type and schema specified" do
-      assert_raise ArgumentError, ~r/Both :type and :schema options were specified/,  fn ->
+      assert_raise ArgumentError, ~r/Both :type and :schema options were specified/, fn ->
         @controller.open_api_operation(:non_exlusive_paramter_type_schema_docs)
       end
     end

test/json_api_helpers_test.exs

@@ -0,0 +1,82 @@
+defmodule OpenApiSpex.JsonApiHelpersTest do
+  use ExUnit.Case, async: true
+
+  alias OpenApiSpexTest.{CartDocument, CartIndexDocument, CartResource}
+  alias OpenApiSpex.{JsonApiHelpers, Schema}
+  alias OpenApiSpex.JsonApiHelpers.JsonApiResource
+
+  describe "from operation specs" do
+    test "index action" do
+      spec = OpenApiSpexTest.ApiSpec2.spec()
+      assert %Schema{} = _schema = spec.components.schemas["CartIndexResponse"]
+    end
+  end
+
+  describe "generate_resource_document/1" do
+    test "generate schema/0" do
+      assert %Schema{} = schema = CartDocument.schema()
+      assert schema.title == "CartDocument"
+      assert %{data: _} = schema.properties
+      assert schema.properties.data.title == CartResource.schema().title
+    end
+
+    test "generate schema for index document" do
+      assert %Schema{} = schema = CartIndexDocument.schema()
+      assert schema.title == "CartIndexDocument"
+      assert %{data: _} = schema.properties
+      assert schema.properties.data.type == :array
+      assert schema.properties.data.items == OpenApiSpexTest.CartResource
+    end
+  end
+
+  describe "generate_resource_schema/1" do
+    test "generate resource/0 and resource_schema/0" do
+      assert %JsonApiResource{} = CartResource.resource()
+      assert %Schema{} = schema = CartResource.schema()
+      assert schema.title == "CartResource"
+    end
+  end
+
+  describe "resource_schema/1" do
+    test "attributes" do
+      resource = CartResource.resource()
+      schema = JsonApiHelpers.resource_schema(resource)
+      assert schema.properties.attributes == JsonApiResource.attributes_schema(resource)
+      assert %Schema{} = schema.properties.id
+      assert %Schema{} = schema.properties.type
+    end
+
+    test "title" do
+      resource = CartResource.resource()
+      schema = JsonApiHelpers.resource_schema(resource)
+      assert schema.title == "CartResource"
+    end
+  end
+
+  describe "attributes_schema/1" do
+    test "generates schema with same properties" do
+      resource = CartResource.resource()
+      schema = JsonApiResource.attributes_schema(resource)
+      assert schema.properties == resource.properties
+    end
+
+    test "generates title" do
+      resource = CartResource.resource()
+      schema = JsonApiResource.attributes_schema(resource)
+      assert schema.title == "CartAttributes"
+    end
+
+    test ":title must be a string" do
+      resource = CartResource.resource()
+      resource = %{resource | title: nil}
+
+      assert_raise(
+        RuntimeError,
+        "%JsonApiResource{} :title is required and must be a string",
+        fn ->
+          JsonApiResource.attributes_schema(resource)
+        end
+      )
+    end
+  end
+end

test/support/api_spec.ex

@@ -24,7 +24,7 @@ defmodule OpenApiSpexTest.ApiSpec do
       },
       components: %Components{
         schemas:
-          for schemaMod <- [
+          for schema_mod <- [
                 Schemas.Pet,
                 Schemas.PetType,
                 Schemas.Cat,
@@ -35,7 +35,7 @@ defmodule OpenApiSpexTest.ApiSpec do
                 Schemas.Primitive
               ],
               into: %{} do
-            schema = schemaMod.schema()
+            schema = schema_mod.schema()
             {schema.title, schema}
           end
       },

test/support/api_spec_2.ex

@@ -0,0 +1,30 @@
+defmodule OpenApiSpexTest.ApiSpec2 do
+  alias OpenApiSpex.{OpenApi, Contact, License, Paths, Server, Info}
+  alias OpenApiSpexTest.Router2
+
+  @behaviour OpenApi
+
+  @impl OpenApi
+  def spec() do
+    %OpenApi{
+      servers: [
+        %Server{url: "http://example.com"}
+      ],
+      info: %Info{
+        title: "A",
+        version: "3.0",
+        contact: %Contact{
+          name: "joe",
+          email: "[email protected]",
+          url: "https://help.joe.com"
+        },
+        license: %License{
+          name: "MIT",
+          url: "http://mit.edu/license"
+        }
+      },
+      paths: Paths.from_router(Router2)
+    }
+    |> OpenApiSpex.resolve_schema_modules()
+  end
+end

test/support/cart_document.ex

@@ -0,0 +1,11 @@
+defmodule OpenApiSpexTest.CartDocument do
+  alias OpenApiSpex.JsonApiHelpers
+  alias OpenApiSpexTest.CartResource
+
+  require OpenApiSpex.JsonApiHelpers
+
+  JsonApiHelpers.generate_document_schema(
+    title: "CartDocument",
+    resource: CartResource.resource()
+  )
+end

test/support/cart_index_document.ex

@@ -0,0 +1,12 @@
+defmodule OpenApiSpexTest.CartIndexDocument do
+  alias OpenApiSpex.JsonApiHelpers
+  alias OpenApiSpexTest.CartResource
+
+  require OpenApiSpex.JsonApiHelpers
+
+  JsonApiHelpers.generate_document_schema(
+    title: "CartIndexDocument",
+    multiple: true,
+    resource: CartResource
+  )
+end

test/support/cart_resource.ex

@@ -0,0 +1,14 @@
+defmodule OpenApiSpexTest.CartResource do
+  alias OpenApiSpex.JsonApiHelpers
+  alias OpenApiSpex.Schema
+
+  require OpenApiSpex.JsonApiHelpers
+
+  JsonApiHelpers.generate_resource_schema(
+    title: "Cart",
+    properties: %{
+      total: %Schema{type: :integer}
+    },
+    additionalProperties: false
+  )
+end