-
Notifications
You must be signed in to change notification settings - Fork 61
wip: swagger api docs #3882
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.
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
Draft
mtuchi
wants to merge
10
commits into
main
Choose a base branch
from
api-docs
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Draft
wip: swagger api docs #3882
Changes from all commits
Commits
Show all changes
10 commits
Select commit
Hold shift + click to select a range
0569fa4
generate postman collections
mtuchi e6fb377
generate api docs
mtuchi 165614e
setup docout to extract api docs
mtuchi ad0ab04
setup bureaucrat for generating API docs
mtuchi ad960aa
config docout
mtuchi 9d5291e
add docout, poison and bureaucrat
mtuchi f05c607
setup bureaucrat
mtuchi a80d0cd
minify postman.json
mtuchi 8571616
minify docs.json
mtuchi 0e9259c
fix dialyzer error
mtuchi File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or 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
This file contains hidden or 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
This file contains hidden or 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
This file contains hidden or 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
This file contains hidden or 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,177 @@ | ||
| defmodule LightningWeb.DocoutFormatter do | ||
| @moduledoc """ | ||
| Docout formatter that extracts module and function docs to JSON. | ||
|
|
||
| Processes documentation from modules tagged with `@moduledoc docout: true` | ||
| and converts them into a structured JSON format suitable for API | ||
| documentation generation. | ||
|
|
||
| ## Output Format | ||
|
|
||
| The formatter generates JSON with the following structure: | ||
|
|
||
| [ | ||
| { | ||
| "module": "Elixir.MyModule", | ||
| "moduledoc": "Module documentation string", | ||
| "functions": [ | ||
| { | ||
| "name": "my_function", | ||
| "arity": 2, | ||
| "doc": "Function documentation", | ||
| "metadata": {} | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
|
|
||
| ## Usage | ||
|
|
||
| This formatter is automatically invoked by the Docout library when | ||
| running documentation generation tasks: | ||
|
|
||
| mix docs.generate | ||
|
|
||
| The output is written to `priv/static/docs.json`. | ||
| """ | ||
|
|
||
| use Docout, output_path: "priv/static/docs.json" | ||
|
|
||
| @type doc_entry :: {module(), moduledoc(), metadata(), functions()} | ||
| @type moduledoc :: map() | binary() | :none | :hidden | nil | ||
| @type metadata :: map() | ||
| @type functions :: [function_entry()] | ||
| @type function_entry :: | ||
| {{:function, atom(), non_neg_integer()}, doc_content(), metadata()} | ||
| @type doc_content :: map() | binary() | :none | :hidden | nil | ||
|
|
||
| @doc """ | ||
| Formats the documentation list into JSON. | ||
|
|
||
| Takes a list of documentation entries from Docout and converts them | ||
| into a pretty-printed JSON string. | ||
|
|
||
| ## Parameters | ||
|
|
||
| - doc_list: List of documentation tuples from Docout | ||
|
|
||
| ## Returns | ||
|
|
||
| Pretty-printed JSON string of all documentation | ||
|
|
||
| ## Examples | ||
|
|
||
| iex> format([{MyModule, %{}, %{}, []}]) | ||
| ~s([{\\n "module": "Elixir.MyModule",\\n ...}]) | ||
|
|
||
| """ | ||
| @spec format([doc_entry()]) :: String.t() | ||
| def format(doc_list) do | ||
| doc_list | ||
| |> Enum.map(&format_module/1) | ||
| |> Jason.encode!(pretty: true) | ||
| end | ||
|
|
||
| # Formats a module documentation tuple into a structured map. | ||
| # Structure: {module, moduledoc_map, metadata_map, function_list} | ||
| @spec format_module(doc_entry()) :: map() | ||
| defp format_module({module, moduledoc, _metadata, functions}) do | ||
| %{ | ||
| module: inspect(module), | ||
| moduledoc: extract_moduledoc(moduledoc), | ||
| functions: | ||
| functions | ||
| |> Enum.map(&format_function/1) | ||
| |> Enum.reject(&is_nil/1) | ||
| } | ||
| end | ||
|
|
||
| # Formats a function documentation entry into a map. | ||
| # Returns nil for hidden functions or non-function entries. | ||
| @spec format_function(function_entry() | any()) :: map() | nil | ||
| defp format_function({{:function, _name, _arity}, :hidden, _metadata}) do | ||
| nil | ||
| end | ||
|
|
||
| defp format_function({{:function, name, arity}, doc, metadata}) do | ||
| %{ | ||
| name: to_string(name), | ||
| arity: arity, | ||
| doc: extract_doc(doc), | ||
| metadata: sanitize_metadata(metadata || %{}) | ||
| } | ||
| end | ||
|
|
||
| # Skip non-function entries (like :macro, :type, etc) | ||
| defp format_function(_), do: nil | ||
|
|
||
| # Converts metadata to JSON-safe format | ||
| @spec sanitize_metadata(map() | any()) :: map() | ||
| defp sanitize_metadata(metadata) when is_map(metadata) do | ||
| metadata | ||
| |> Enum.map(fn {key, value} -> {key, sanitize_value(value)} end) | ||
| |> Enum.into(%{}) | ||
| end | ||
|
|
||
| defp sanitize_metadata(_), do: %{} | ||
|
|
||
| # Converts various Elixir types to JSON-safe values | ||
| @spec sanitize_value(any()) :: any() | ||
| defp sanitize_value(value) when is_binary(value), do: value | ||
| defp sanitize_value(value) when is_number(value), do: value | ||
| defp sanitize_value(value) when is_boolean(value), do: value | ||
| defp sanitize_value(value) when is_atom(value), do: to_string(value) | ||
|
|
||
| defp sanitize_value(value) when is_list(value) do | ||
| # Check if it's a charlist or regular list | ||
| if charlist?(value) do | ||
| to_string(value) | ||
| else | ||
| Enum.map(value, &sanitize_value/1) | ||
| end | ||
| end | ||
|
|
||
| defp sanitize_value(value) when is_tuple(value) do | ||
| value | ||
| |> Tuple.to_list() | ||
| |> Enum.map(&sanitize_value/1) | ||
| end | ||
|
|
||
| defp sanitize_value(value) when is_map(value) do | ||
| value | ||
| |> Enum.map(fn {k, v} -> | ||
| {sanitize_value(k), sanitize_value(v)} | ||
| end) | ||
| |> Enum.into(%{}) | ||
| end | ||
|
|
||
| defp sanitize_value(_), do: nil | ||
|
|
||
| # Checks if a list is a charlist (printable ASCII) | ||
| @spec charlist?(list()) :: boolean() | ||
| defp charlist?(value) do | ||
| Enum.all?(value, &is_integer/1) and List.ascii_printable?(value) | ||
| end | ||
|
|
||
| # Extracts moduledoc content from various formats | ||
| @spec extract_moduledoc(moduledoc()) :: String.t() | nil | ||
| defp extract_moduledoc({:docs_v1, _, _, _, %{"en" => doc}, _, _}) do | ||
| doc | ||
| end | ||
|
|
||
| defp extract_moduledoc(%{"en" => doc}), do: doc | ||
| defp extract_moduledoc(doc) when is_binary(doc), do: doc | ||
| defp extract_moduledoc(nil), do: nil | ||
| defp extract_moduledoc(:none), do: nil | ||
| defp extract_moduledoc(:hidden), do: nil | ||
| defp extract_moduledoc(_), do: nil | ||
|
|
||
| # Extracts function doc content from various formats | ||
| @spec extract_doc(doc_content()) :: String.t() | nil | ||
| defp extract_doc(%{"en" => doc}), do: doc | ||
| defp extract_doc(doc) when is_binary(doc), do: doc | ||
| defp extract_doc(nil), do: nil | ||
| defp extract_doc(:none), do: nil | ||
| defp extract_doc(:hidden), do: nil | ||
| defp extract_doc(_), do: nil | ||
| end |
This file contains hidden or 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
This file contains hidden or 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
Oops, something went wrong.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is partly AI generated (80% ish). I am not sure what most of these codes mean but it does the job.
This is how i extract
@moduledocand@doccomments from API Controllers likeworkflows_controller.exThe goal is to link these docs as description in postman collection requests