> For the complete documentation index, see [llms.txt](https://framework.aic.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://framework.aic.io/technical-guidelines-code-standards-and-tech-stack/asp.net-core-web-api-standards/openapi-and-api-documentation.md).

# 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

```csharp
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