OpenAPI Specification

The Wrapsfer API exposes a generated OpenAPI document via Microsoft.AspNetCore.OpenApi. The document is registered for every environment but only mapped in Development, so it is reachable on local and Compose runs but not from a production deployment.

How It Is Wired

In src/Wrapsfer.Api/Program.cs:

builder.Services.AddOpenApi();
// …
if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

• AddOpenApi() registers the OpenAPI document generator in the DI container. The package is Microsoft.AspNetCore.OpenApi 10.0.7 (declared in Wrapsfer.Api.csproj).
• MapOpenApi() adds the HTTP endpoint that serves the generated document. The call sits inside if (app.Environment.IsDevelopment()), so the endpoint is only routed when ASPNETCORE_ENVIRONMENT=Development.

No additional configuration is supplied — there is no custom document title, version, server, or security scheme today. The output is whatever Microsoft.AspNetCore.OpenApi produces from the registered controllers, which today means just the greeting endpoint.

The Endpoint

Method	Path	Availability
GET	/openapi/v1.json	Development only

In Development:

curl -i http://localhost:8080/openapi/v1.json

Returns 200 OK with Content-Type: application/json containing the OpenAPI v1 document. The path is the package's default for the unnamed document (v1); it is not customized in source.

In any other environment the route is not mapped and requests return 404 Not Found from ASP.NET Core's endpoint router.

The default launch profiles in src/Wrapsfer.Api/Properties/launchSettings.json set ASPNETCORE_ENVIRONMENT=Development, and docker-compose.yml does the same. So the endpoint is reachable in both default local flows. See Getting Started for the URL that matches your launch method.

Common Uses

Once you have the document, typical workflows include:

• Endpoint discovery. Read or render the document to see every route, parameter, and response shape exposed by the API.
• API exploration tools. Point a renderer such as Swagger UI, Redoc, or your IDE's HTTP client at /openapi/v1.json to browse and try requests interactively.
• Client generation. Run a generator (for example openapi-generator, Kiota, or NSwag) against the document to produce typed clients in TypeScript, C#, Python, and so on.
• Contract checks. Diff successive versions of the document in CI to surface breaking changes to the public surface.

These are uses you can apply to the generated document — none of them are wired into the repository today.

Production Exposure

OpenAPI is not exposed outside Development unless Program.cs is intentionally changed. The current code gates MapOpenApi() behind IsDevelopment(), so promoting the API to Staging or Production (by setting ASPNETCORE_ENVIRONMENT accordingly) silently removes the endpoint without any further configuration.

If exposing the document beyond local is desired later, the change should be deliberate and considered alongside:

• whether the document should be served behind authentication,
• whether to publish a static, versioned copy artifact rather than a live endpoint,
• whether to restrict CORS / network access to the route.

Until that decision is made, treat the absence of /openapi/v1.json outside Development as the intended behavior.

See Also

• Endpoint Reference — /openapi/v1.json listed alongside the other endpoints.
• API Overview — OpenAPI listed under the current stack and dev-only availability.
• Getting Started — how to reach the local URL that hosts the document.
• Configuration — ASPNETCORE_ENVIRONMENT and other host-level settings that determine whether the endpoint is mapped.