AppSurface Search
Section API Reference
API Reference Language: C# Component: OpenApi Audience: developer

OpenApi

Type

AppSurfaceWebOpenApiModule

Source

A web module that integrates OpenAPI/Swagger document generation into the application.

Remarks

Use AppSurfaceWebOpenApiModule when AppSurface should own the default OpenAPI service and endpoint wiring for an app. The module registers ASP.NET Core OpenAPI generation, endpoint API exploration, document and operation transformers, and maps the OpenAPI endpoint during endpoint configuration when AppSurfaceWebOpenApiOptions.ExposeEndpoint allows the active environment. The default document title is {ApplicationName} | v1 , and the built-in transformers remove the framework implementation tag ForgeTrust.AppSurface.Web while preserving other tags. Register a custom module or add additional OpenAPI options when an application needs multiple documents, custom versioning, authentication metadata, or different tag policies. Pitfall: transformer tag collections may be null and this module must run before consumers expect the MapOpenApi endpoint to be mapped. The production opt-in setting maps the endpoint only; hosts must still protect exposed OpenAPI documents with authorization, private networking, or another deployment boundary.

Method

ConfigureServices

void ConfigureServices(StartupContext context, IServiceCollection services)
Source

Configures services needed for OpenAPI, including document and operation transformers to customize the generated schema.

Parameters

  • context
    The startup context that supplies the application name used in the generated document title.
  • services
    The service collection receiving OpenAPI and endpoint exploration registrations.

Remarks

ConfigureServices reads StartupContext.ApplicationName for the default document title, registers singleton-safe transformer delegates through ASP.NET Core OpenAPI options, and adds endpoint API exploration. Call this through normal AppSurface module startup rather than invoking it after the host service provider has been built.

Method

ConfigureEndpoints

void ConfigureEndpoints(StartupContext context, IEndpointRouteBuilder endpoints)
Source

Maps the OpenAPI document endpoint when AppSurfaceWebOpenApiOptions.ExposeEndpoint allows it.

Parameters

  • context
    The startup context.
  • endpoints
    The endpoint route builder.
Method

RegisterDependentModules

void RegisterDependentModules(ModuleDependencyBuilder builder)
Source

Registers dependencies for this module; currently no implementation is required.

Parameters

  • builder
    The module dependency builder.
Method

ConfigureHostBeforeServices

void ConfigureHostBeforeServices(StartupContext context, IHostBuilder builder)
Source

Executes pre-service host configuration; currently no implementation is required.

Parameters

  • context
    The startup context.
  • builder
    The host builder.
Method

ConfigureHostAfterServices

void ConfigureHostAfterServices(StartupContext context, IHostBuilder builder)
Source

Executes post-service host configuration; currently no implementation is required.

Parameters

  • context
    The startup context.
  • builder
    The host builder.
Method

ConfigureWebApplication

void ConfigureWebApplication(StartupContext context, IApplicationBuilder app)
Source

Configures the web application pipeline; currently no implementation is required.

Parameters

  • context
    The startup context.
  • app
    The application builder.
Type

AppSurfaceWebOpenApiOptions

Source

Configures AppSurface's OpenAPI endpoint mapping behavior.

Remarks

The default ExposeEndpoint value keeps the generated OpenAPI document available during development while avoiding accidental production metadata exposure. Set ExposeEndpoint to AppSurfaceApiDocumentationEndpointExposure.Always only when the endpoint is intentionally available outside development and is protected by host-owned controls such as authorization, private networking, or a reverse proxy policy.

Property

ExposeEndpoint

AppSurfaceApiDocumentationEndpointExposure ExposeEndpoint { get; set; } Source

Gets or sets when the generated OpenAPI document endpoint should be mapped.

Enum

AppSurfaceApiDocumentationEndpointExposure

Source

Controls when AppSurface-owned API documentation endpoints are mapped by web modules.

Remarks

Use DevelopmentOnly for the safe default: local development hosts get zero-configuration API docs, while non-development hosts must opt into exposure. Use Always only when the host protects the endpoint with authentication, authorization, network controls, or another deployment boundary. This setting only controls whether AppSurface maps the endpoint; it does not add authorization by itself. Numeric values are part of the public configuration and serialization contract. Do not reorder or renumber existing members; changing these assignments can break persisted configuration, serialized payloads, and consumers. Add new modes by appending members with new explicit values.