OpenApiInstaller — Web

Key: OpenApi
Default Enabled: ✅
Package: SaveApis.Framework.Web

---

Purpose

Generates an OpenAPI (v3) document from the registered controllers and exposes it at /openapi/v1.json. When Zitadel is enabled, the document is automatically enhanced with an OAuth2 Authorization Code security scheme.

---

What It Does

Builder phase:

• Calls builder.Services.AddOpenApi() using the built-in ASP.NET Core OpenAPI support
• If ZitadelInstaller is enabled (or not explicitly disabled): adds an IOpenApiDocumentTransformer that injects:
  • An OAuth2 Authorization Code security scheme named Zitadel
  • Authorization URL: {Zitadel:Authority}oauth/v2/authorize
  • Token URL: {Zitadel:Authority}oauth/v2/token
  • Scopes: from Zitadel:Scopes configuration

Application phase:

• Maps /openapi/v1.json with AllowAnonymous() (the document itself is always public)

---

Dependencies

Dependency	Direction	Requirement	Description
AuthenticationInstaller	After	Optional
AuthorizationInstaller	After	Optional
ZitadelInstaller	After	Optional	Required to inject the Zitadel security scheme
ControllerInstaller	After	Required	Controllers must be registered before OpenAPI document is generated
ScalarInstaller	Before	Optional	Scalar reads the OpenAPI document

---

Configuration

This installer has no dedicated configuration section. It reads Zitadel:Authority and Zitadel:Scopes from the Zitadel section (via GetOption<ZitadelOptions>) to build the security scheme.

See ZitadelInstaller configuration for those options.

---

InstallerContext Extension

installer.WithOpenApi(bool enabled = true);

Example — disable in production:

if (!builder.Environment.IsDevelopment())
    installer.WithOpenApi(false);

---

Notes

• The OpenAPI document is accessible at /openapi/v1.json regardless of environment.
• The endpoint uses AllowAnonymous() so the document is publicly accessible even when RequireAuthorization() is applied globally by ControllerInstaller.
• The security scheme check is context.Enabled(ZitadelInstaller.Key) ?? true — meaning Zitadel is assumed enabled unless explicitly disabled. Disable with installer.WithZitadel(false) to remove the security scheme.

---

Related

• Web Framework Overview
• ControllerInstaller — controllers must be registered first
• ZitadelInstaller — provides the security scheme details
• ScalarInstaller — renders the OpenAPI document as a UI