Skip to content

feat: New Mix Task for Generating Static Markdown Swagger Page for ExDoc #679

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

feat: New Mix Task for Generating Static Markdown Swagger Page for ExDoc #679

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b6e2711
feat: New Mix Task for Generating Static Markdown Swagger Page for ExDoc
bradschwartz Jul 31, 2025
b60666b
bump to latest swagger version
bradschwartz Aug 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
100 changes: 100 additions & 0 deletions lib/mix/tasks/openapi.static_docs.ex
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
defmodule Mix.Tasks.Openapi.StaticDocs do
@shortdoc "Generate a static file that renders the OpenAPI spec using the Swagger UI"
@moduledoc """
Generate a static file that renders the OpenAPI spec using the Swagger UI. Uses
assets from https://unpkg.com/swagger-ui-dist.

## Examples

$ mix openapi.static_docs --spec PhoenixAppWeb.ApiSpec --output-file swagger.md
$ mix openapi.static_docs --spec PhoenixAppWeb.ApiSpec --output-file swagger.md --swagger-version 5.27.1

## Usage with ExDoc

To use with ExDoc, you can add the following to your `mix.exs` file:

```elixir
def docs do
[
extras: ["guides/swagger.md"]
]
end

def aliases do
[
"docs": [
"cmd mkdir -p guides/",
"openapi.static_docs --spec PhoenixAppWeb.ApiSpec --output-file guides/swagger.md --swagger-version 4.4.0",
"docs"
]
]
end
```

## Command line options

Accepts all the same options as `Mix.Tasks.Openapi.Spec.Json` plus:

* `--output-file` - The file to write the static file to (defaults to `swagger.md`)

* `--swagger-version` - The version of the Swagger UI to use (defaults to `5.27.1`)
"""
use Mix.Task

require Mix.Generator

alias Mix.Tasks.Openapi.Spec.Json

@recursive true
@default_static_filename "swagger.md"
@default_swagger_version "5.27.1"

@static_template """
# <%= spec_name %>

<head>
<link rel="stylesheet" href="https://unpkg.com/swagger-ui-dist@<%= swagger_version %>/swagger-ui.css" />
</head>

<body>
<div id="swagger-ui"></div>
<script src="https://unpkg.com/swagger-ui-dist@<%= swagger_version %>/swagger-ui-bundle.js" crossorigin></script>
<script src="https://unpkg.com/swagger-ui-dist@<%= swagger_version %>/swagger-ui-standalone-preset.js" crossorigin></script>
<script>
window.onload = () => {
window.ui = SwaggerUIBundle({
spec: <%= json_spec %>,
dom_id: '#swagger-ui',
});
};
</script>
</body>
"""

@flags [
output_file: :string,
swagger_version: :string,
spec: :string
]

@impl true
def run(argv) do
{opts, _, _} = OptionParser.parse(argv, switches: @flags)

json_spec_filename = Json.run(argv)

output_file = Keyword.get(opts, :output_file, @default_static_filename)
swagger_version = Keyword.get(opts, :swagger_version, @default_swagger_version)

json_spec = File.read!(json_spec_filename)

rendered_template =
EEx.eval_string(@static_template,
spec_name: opts[:spec],
json_spec: json_spec,
swagger_version: swagger_version
)

Mix.Generator.create_file(output_file, rendered_template, force: true, quiet: true)
end
end
5 changes: 4 additions & 1 deletion lib/open_api_spex/export_spec.ex
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ defmodule OpenApiSpex.ExportSpec do
quiet: false
end

@spec call(list(binary()), (any(), any() -> any()), String.t()) :: false | nil | String.t()
def call(argv, encode_spec, default_filename) do
opts = parse_options(argv, default_filename)

Expand Down Expand Up @@ -86,7 +87,9 @@ defmodule OpenApiSpex.ExportSpec do
dir -> Mix.Generator.create_directory(dir, quiet: opts.quiet)
end

Mix.Generator.create_file(opts.filename, content, force: true, quiet: opts.quiet)
with true <- Mix.Generator.create_file(opts.filename, content, force: true, quiet: opts.quiet) do
Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

i found it easier to update here on successful writes to return the new filename, instead of having the new task have to explicitly be aware of the :filename switch for the json task. Happy to go with that if preferable tho

opts.filename
end
end

defp find_spec(opts) do
Expand Down