Swagger / OpenAPI

Swagger UI and OpenAPI generation are supplied by Microtec.Web.Hosting. This page covers Swagger usage; the complete route, version, migration, minimal-endpoint, and gateway contract is in API Versioning.

---

Availability by Environment

Environment	Swagger UI	OpenAPI JSON	Auth required
dev	Enabled	Enabled	No
stage	Enabled	Enabled	No, but protected by the AFD WAF IP allowlist
preprod	Disabled	Disabled	N/A
uat	Disabled	Disabled	N/A
production	Disabled	Disabled	N/A

Why Swagger Is Disabled in Production

Swagger exposes parameter names, response schemas, and security metadata. Production API details are shared with approved integration partners through direct channels instead of a public Swagger UI.

---

Shared Registration

Do not register Swagger documents manually in each service. Use the shared web extensions:

builder.Services.AddSharedWeb(builder.Configuration, builder.Environment);

var app = builder.Build();
app.ConfigureSharedWeb(builder.Configuration);

Swagger middleware is controlled independently from API versioning:

{
  "EnableSwagger": true
}

---

Versioned Documents

API Versioning creates one OpenAPI document per discovered version:

/swagger/v1/swagger.json
/swagger/v2/swagger.json

Swagger UI is available at /swagger when enabled. It loads every discovered document and labels each one with its application name and version.

API behavior	Swagger behavior
/api/v1/... endpoint	Appears only in document v1.
/api/v2/... endpoint	Appears only in document v2.
v2-only endpoint	Does not appear in v1.
Route token {version:apiVersion}	Is rendered as a concrete path such as /api/v1/....
Endpoint with no explicit group	Appears only in the default document, normally v1.

Use API Versioning for controller and minimal-endpoint patterns, every ApiVersioning option, compatibility migration, and gateway version setup.

---

JWT Bearer Authentication

1. Open the target Swagger UI.
2. Select Authorize.
3. Obtain a Keycloak access token for the target environment.
4. Enter Bearer <access-token> in the Bearer scheme.
5. Submit requests through Swagger UI.

Swagger also exposes the XApiKey scheme for endpoints that require an application API key.

Token Expiry

Keycloak access tokens expire. When Swagger requests start returning 401 Unauthorized, obtain a fresh token and authorize again.

---

Operation Metadata

Controllers should include XML comments and response metadata so the generated document is useful to callers:

/// <summary>
/// Gets a paginated list of journal entries.
/// </summary>
/// <param name="query">Filter and pagination parameters.</param>
/// <response code="200">Returns journal entry summaries.</response>
/// <response code="401">The caller is not authenticated.</response>
[HttpGet]
[ProducesResponseType(typeof(ApiResponse<PagedResult<JournalEntryDto>>), StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status401Unauthorized)]
public async Task<IActionResult> GetAll([FromQuery] GetAllJournalEntryQuery query) { ... }

Use [ProducesResponseType] on public controller actions. Minimal endpoints should use .Produces<T>(...) and related metadata methods.

---

Gateway Swagger

Gateway Swagger UI is available at /gateway/swagger. It lists the gateway document and configured downstream service documents. The complete configuration is in API Versioning - Gateway Swagger Aggregation.

The downstream document endpoint is:

/gateway/swagger/docs/{serviceName}/{version}/swagger.json

---

OpenAPI Spec Export

Download a version-specific document to generate a client:

curl https://gateway.microtecstage.com/swagger/v1/swagger.json \
  -o accounting-api-v1.json

npx @openapitools/openapi-generator-cli generate \
  -i accounting-api-v1.json \
  -g typescript-axios \
  -o ./generated/accounting-client

Generated Clients

Microtec.PublicApi.* packages are the supported typed clients for inter-service communication. Regenerate or publish the appropriate package when an API contract changes instead of hand-writing a parallel client.