Support generating OpenAPI spec files with Mix tasks

[davidebriani]

The PR adds support for generating OpenAPI spec files with Mix tasks, instead of just in response to HTTP requests to the OpenAPI route.

Some new options are introduced that helps customizing the resulting spec:

• The OpenAPI title is now configurable with the :open_api_title opt.
• The OpenAPI version is now configurable with the :open_api_version opt.
• The OpenAPI server list was previously populated by getting the endpoint from a live conn. Since we want to support spec generation from the CLI and without access to an active connection, a new option :phoenix_endpoint is supported to statically provide a reference to the endpoint. Another option :open_api_servers is added if the user instead wants to specify a custom list of URLs.

defmodule MyAppWeb.AshJsonApi do
  use AshJsonApi.Router,
    domains: [...],
    open_api: "/open_api",
    open_api_title: "Title",
    open_api_version: "1.0.0",
    open_api_servers: ["http://domain.com/api/v1"],
    phoenix_endpoint: MyAppWeb.Endpoint
end

The OpenAPI spec can be written to file using the Mix tasks provided by OpenApiSpex.

mix openapi.spec.json --spec MyAppWeb.AshJsonApi
mix openapi.spec.yaml --spec MyAppWeb.AshJsonApi

A new section is added to the documentation to describe how to use the new options and how to generate the spec file via CLI.

Fixes #129

Contributor checklist

• [ ] Bug fixes include regression tests
• [ ] Features include unit/acceptance tests

[zachdaniel]

YES 🙇

There is one major thing that I would like to see, but we will need to PR it to open_api_spex, which is a --check option, which fails with a message if the open api spec that is generated does not match the existing one. This allows people to put this mix task in their CI pipeline to ensure that the files don't get out of sync.

[zachdaniel]

Actually, perhaps we should make our own wrapper tasks that support the --check option. This also gives us a chance to enrich those tasks further in the future if needed? i.e mix ash_json_api.spec.json and mix ash_json_api.spec.yaml?

[zachdaniel]

For now, we can merge this as-is though, and consider that option as a follow up. Great work! 🥳

[zachdaniel]

One other thing I'd like to follow up with is to support actually using the generated file, instead of regenerating it each time. This will make the schema faster to load as well.