AppSurfaceApiDocumentationEndpointExposure ExposeEndpoint { get; set; }
Source
Gets or sets when the generated OpenAPI document endpoint should be mapped.
OpenApi
AppSurfaceApiDocumentationEndpointExposure
SourceControls 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.
AppSurfaceWebOpenApiModule
SourceA 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.
ConfigureServices
void ConfigureServices(StartupContext context, IServiceCollection services)
Source
Configures services needed for OpenAPI, including document and operation transformers to customize the generated schema.
Parameters
contextThe startup context that supplies the application name used in the generated document title.servicesThe 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.
ConfigureEndpoints
void ConfigureEndpoints(StartupContext context, IEndpointRouteBuilder endpoints)
Source
Maps the OpenAPI document endpoint when AppSurfaceWebOpenApiOptions.ExposeEndpoint allows it.
Parameters
contextThe startup context.endpointsThe endpoint route builder.
RegisterDependentModules
void RegisterDependentModules(ModuleDependencyBuilder builder)
Source
Registers dependencies for this module; currently no implementation is required.
Parameters
builderThe module dependency builder.
ConfigureHostBeforeServices
void ConfigureHostBeforeServices(StartupContext context, IHostBuilder builder)
Source
Executes pre-service host configuration; currently no implementation is required.
Parameters
contextThe startup context.builderThe host builder.
ConfigureHostAfterServices
void ConfigureHostAfterServices(StartupContext context, IHostBuilder builder)
Source
Executes post-service host configuration; currently no implementation is required.
Parameters
contextThe startup context.builderThe host builder.
ConfigureWebApplication
void ConfigureWebApplication(StartupContext context, IApplicationBuilder app)
Source
Configures the web application pipeline; currently no implementation is required.
Parameters
contextThe startup context.appThe application builder.
AppSurfaceWebOpenApiOptions
SourceConfigures 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.