OpenAPI and API Documentation

Purpose

OpenAPI documentation allows consumers, testers, governance teams and security reviewers to understand the API contract.

AIC Standard

• Every Web API MUST generate an OpenAPI document unless explicitly exempt.

• OpenAPI output must be reviewed for public or customer-facing APIs.

• Security schemes must be represented accurately.

• Error responses must be documented.

• API version must be visible.

• OpenAPI documents should be stored as release evidence for external APIs.

Required Metadata

OpenAPI documents should include:

• title

• version

• description

• contact or owner

• authentication scheme

• authorization notes where possible

• endpoint tags

• request schemas

• response schemas

• error schemas

Example

builder.Services.AddOpenApi();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
}

Documentation Review

Before release:

• remove internal-only endpoints from public docs

• verify examples do not include sensitive data

• verify schemas reflect nullable and required fields

• verify status codes are correct

• verify authentication is documented

• verify versioning is clear

Contract Evidence

For customer-facing APIs, retain:

• OpenAPI JSON or YAML

• API design review

• consumer approval where applicable

• breaking change assessment

• test results