Alternative operation specs API

[moxley]

Fixes #242

Introduces an API for operation specs that is meant as an alternative to the @doc tag-based operation specs API. The syntax is just as clean and easy to use as the @doc tag-based operations specs. Supports the same shortcuts that the @doc tag-based API supports.

See test/support/dsl_controller.ex for example usage.

defmodule MyController do
  use Phoenix.Controller
  use OpenApiSpex.ControllerSpecs

  tags ["users"]
  security [%{}, %{"petstore_auth" => ["write:pets", "read:pets"]}]

  operation :update,
    summary: "Update user",
    parameters: [
      id: [
        in: :path,
        description: "User ID",
        type: :integer,
        example: 1001
      ]
    ],
    request_body: {"User params", "application/json", UserParams},
    responses: [
      ok: {"User response", "application/json", UserResponse}
    ]

  def update(conn, %{"id" => id}) do
    json(conn, %{
      data: %{
        id: id,
        name: "joe user",
        email: "joe@gmail.com"
      }
    })
  end

[mbuhot]

@moxley I'm happy to go with this, perhaps with an experimental note, until it gets some real usage (like we did with the @doc DSL).

[mbuhot]

👍 Moving this into its own module looks good.

[mbuhot]

This may still need a __using__ macro to inject the open_api_operation(action) function into the controller?
I like the way that having a callback between the framework and user code allows the operation DSL to be changed or customized.

[moxley]

Indeed, this will need to automatically define operation_api_operation(action) for each action. Commit 4e1e1e9 does that now. It still does this without leveraging the __using__ macro. If we can avoid requiring a call to use ..., that may make a slightly better API.

[mbuhot]

This DSL looks good.
I had a play around with some other syntaxes, eg

@operation show: [
...
]

operation :show do
...
end

But I think just dropping the parens makes it feel like a module level declaration, eg:

  operation :show, [
    summary: "Show user",
    parameters: [
      id: [
        in: :path,
        description: "User ID",
        type: :integer,
        example: 1001
      ]
    ]
  ]
  def show(conn, %{id: id}) do
    json(conn, %{
      data: %{
        id: id,
        name: "joe user",
        email: "joe@gmail.com"
      }
    })
  end

And it will be easier find the operation/2 macro in the docs vs a magic @ attribute.

[moxley]

I agree. I'll look into how to get OpenApiSpex to expose Elixir Formatter rules so that users can make one small change to the import_deps: [ ... ] list in their .formatter.exs file to allow optional parentheses for these macro calls.

[moxley]

Elixir Formatter changes: 4cfdba2

[mbuhot]

It might be useful to allow security to be defined like tags at the module level, and have it apply to all operations in the controller.

[moxley]

@mbuhot Do you have any ideas for a better name for the module OperationDsl? The "DSL" part of the name seems unfitting because the syntax looks more like a data structure-based configuration rather than a true DSL (like PhoenixSwagger's DSL).

The new operation/2 and tags/1 macros could be moved to OpenApiSpex.Controller or to OpenApiSpex.Operation. Both those places have drawbacks, but I could be convinced otherwise.

Other names I considered for the module are OperationDefs, OperationHelpers, and ControllerOperations.

[moxley]

@mbuhot Do you have any ideas for a better name for the module OperationDsl? The "DSL" part of the name seems unfitting because the syntax looks more like a data structure-based configuration rather than a true DSL (like PhoenixSwagger's DSL).

The new operation/2 and tags/1 macros could be moved to OpenApiSpex.Controller or to OpenApiSpex.Operation. Both those places have drawbacks, but I could be convinced otherwise.

Other names I considered for the module are OperationDefs, OperationHelpers, and ControllerOperations.

I came up with ControllerSpecs. I like that much better than the ones previously mentioned.