Support generating OpenAPI spec files with Mix tasks #200
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
We strive to be able to generate the OpenAPI spec with Mix commands, and not only by querying an HTTP route. As a preliminar step for further developments, move the spec generation to the OpenAPI module in order to have a more reusable `spec` function instead of having it tied to the controller. Notes: - Even though the OpenAPI module is not strictly related to HTTP connections, the spec function accepts a `conn` argument since it was already needed and provided to the `modify_open_api` function, if the user specifies it in the opts. The `conn` argument is nil-able since we want to support spec generation from the CLI. - 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. Signed-off-by: Davide Briani <davide@briani.dev>
If OpenApiSpex is present, the `spec/0` function is exposed on the Router. This allows a user who has already configured AshJsonApi ```elixir defmodule MyAppWeb.AshJsonApi use AshJsonApi.Router, domains: [...], open_api: "/open_api" end ``` to directly generate the OpenAPI spec by running one the Mix tasks from OpenApiSpex: ```sh mix openapi.spec.json --spec MyAppWeb.AshJsonApi mix openapi.spec.yaml --spec MyAppWeb.AshJsonApi ``` Signed-off-by: Davide Briani <davide@briani.dev>
Add some details about the available options to customize the values of the OpenAPI spec. Add a section to describe how the spec files can be generated with Mix tasks. Signed-off-by: Davide Briani <davide@briani.dev>
The option is not supported by OpenApiSpex.Plug.SwaggerUI and has no effect. To configure the title of the OpenAPI spec, a specific option has been added on AshJsonApi.Router. Signed-off-by: Davide Briani <davide@briani.dev>
|
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 |
|
Actually, perhaps we should make our own wrapper tasks that support the |
|
For now, we can merge this as-is though, and consider that option as a follow up. Great work! 🥳 |
|
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. |
This was referenced Jul 5, 2024
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
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:
:open_api_titleopt.:open_api_versionopt.conn. Since we want to support spec generation from the CLI and without access to an active connection, a new option:phoenix_endpointis supported to statically provide a reference to the endpoint. Another option:open_api_serversis added if the user instead wants to specify a custom list of URLs.The OpenAPI spec can be written to file using the Mix tasks provided by OpenApiSpex.
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