Lightning API docs

[mtuchi]

Continue from #673 Next steps

• We need to add support for Open API Spec on lightning. use this library https://github.com/open-api-spex/open_api_spex
• After adding that library create a demo spec eg project_controller_spec.ex to show the structure
• generate openapi.yaml file and put it in a directory that can be fetch via http request, eg static/openapi.yaml
• In docs repo use "docusaurus-plugin-openapi-docs": "^4.5.1", "docusaurus-theme-openapi-docs": "^4.5.1", to generate docs. In docusaurus.config.ts We can specify

 plugins: [
    [
      'docusaurus-plugin-openapi-docs',
      {
        id: 'api',
        docsPluginId: 'classic',
        config: {
          lightning: {
            specPath: 'static/openapi.yaml',
            outputDir: 'docs/api',
            sidebarOptions: {
              groupPathsBy: 'tag',
              categoryLinkSource: 'tag',
            },
          },
        },
      },
    ],
  ],

• It's definitely easier to generating the docs on lightning, So i will have to figure out how to fetch the openapi.yaml form lightning repo. Probably should look on adaptor generate script

Resources

• Docusaurus Plugin OpenAPI
• Public API Docs Concept

[mtuchi]

Okay maybe we need to use swagdox because you get to specify the api on the function using similar syntaxt like hexdoc

defmodule MyApp.UserController do

  @doc """
  Returns a User.

  [Swagdox] API:
    @param id(query), integer, "User ID", required: true

    @response 200, User, "User found"
    @response 403, "User not authorized"
    @response 404, "User not found"

    @security ApiAuth, [read]
  """
  @spec show(any(), map()) :: nil
  def show(_conn, _params) do
    ...
  end
end

[mtuchi]

Read https://elixirforum.com/t/generating-rest-api-docs-by-swagger/57862/15

[mtuchi]

Just a heads up @martalovescoffee i don't think i will be able to work on this issue in this sprint

[mtuchi]

for docs repo https://github.com/kevinswiber/postman2openapi?tab=readme-ov-file#javascript-library

[mtuchi]

Okay i ran into couple of hiccups. Getting Open API spec from lightning using bureaucrat package was really hard I had to switch gear and improvise a bit to generate a Postman collection instead