oapi_generator

OpenAPI descriptions often lack coverage for certain endpoints (e.g., ID-based endpoints that are not publicly documented).

To include these in your generated client, do not modify the official specification. Instead, maintain a separate, supplemental OpenAPI description document containing only the information required to generate the missing endpoints. You can then commit this small supplemental description alongside your client code.

The code generation process is divided into three distinct phases, each using an OpenAPI.State struct to track changes and its own intermediate state struct:

1. Read: Reads the API description (JSON or YAML), dereferences it, and creates an in-memory Elixir representation of the specification.
2. Process: Converts the dereferenced description into specialized structures optimized for code generation.
3. Render: Uses an AST-based renderer to transform the processed API description into formatted Elixir code written to the filesystem.

By default, all generated operation functions call client.request/1.

To make the generated library functional, you must provide a module that implements this function. You can specify which module to use via the output.default_client configuration option. Inside request/1, you can use any HTTP client and implement your preferred error handling logic.

When using this generator to build a library, you are creating a client for an OpenAPI specification. Because specifications change, you must decide how frequently to regenerate and release your code.

Recommended strategies include:

• Rapid/As-needed updates: Use this if the specification adds new endpoints that users want immediately. You can automate this with a scheduled CI job that re-generates code and opens a pull request.
• Periodic updates: Use this if the specification frequently includes fixes or corrections. This reduces maintenance burden while keeping the library stable.
• Version-following: If the specification is well-versioned, align your library's release cadence with the spec's version. It is recommended to include an .api-version file in your release to explicitly communicate which API version your client supports.

Add oapi_generator to your mix.exs dependencies. For most use cases, it is recommended to include it only in the development environment as a non-runtime dependency, as you typically only need the mix api.gen task during development.

If you need to run the generator in production or during testing, adjust the only: :dev and runtime: false options accordingly.

def deps do
  [
    {:oapi_generator, "~> 0.4.0", only: :dev, runtime: false}
  ]
end

If you are managing a library that uses this generator, you can provide contribution guidelines to make it easier for others to submit pull requests that update the generated code.

Effective guidelines should include instructions to:

1. Use the latest commit from the official specification repository.
2. Specify the exact path to the target specification file.
3. Use the mix api.gen default <path_to_spec> command to regenerate code.
4. Update the .api-version file if the specification version has changed.
5. Include the commit SHA of the official specification repository in the PR description.
6. Keep the PR focused strictly on the generated code changes (avoid changing the library version in the same PR).

mix api.gen default path/to/descriptions-next/api.github.com/api.github.com.yaml

The library uses configuration profiles to allow multiple sets of configuration to coexist. All configuration for a specific profile is nested under a top-level key in your config/config.exs.

To use a profile, specify its name when running the generator via the CLI or the OpenAPI.run/2 function.

CLI usage: mix api.gen <profile_name> <path_to_description.json>

Programmatic usage: `OpenAPI.run("<profile_name>", ["path/to/description.json"])

If you are unsure what to name your profile, use default.

# config/config.exs

import Config

config :oapi_generator,
  my_profile: [
    output: [
      base_module: MyClientLibrary
    ]
  ]

Configuration for the OpenAPI Generator is defined using nested keyword lists within a profile in your config/config.exs file. All configuration values must be contained within a profile (e.g., the default profile).

Example structure:

config :oapi_generator, default: [
  output [
    base_module: MyLibrary
  ],
  naming [
    default_operation_module: MyLibrary.Operations
  ]
]

config :oapi_generator, default: [
  output [
    base_module: ...
  ]
]

To implement custom workflows, you can override the default processor or renderer modules in your configuration profile.

By using use OpenAPI.Processor or use OpenAPI.Renderer in your module, you automatically receive default implementations for all callbacks. This allows you to implement only the specific callbacks you need to override.

Implementation Steps

1. Define your module and use the appropriate behaviour:

   defmodule MyLibrary.Renderer do
     use OpenAPI.Renderer
   
     # Override a specific callback
     def write(state, file) do
       # custom implementation
     end
   end

2. Register your module in your application configuration under a profile key:

# config/config.exs

config :oapi_generator,
  my_profile: [
    renderer: MyLibrary.Renderer
  ]