# EndpointDocumentation/advanced

This folder contains **manually created** documentation files for API endpoints that require detailed or custom descriptions beyond what auto-generation provides.

Files placed here are version-controlled in SVN. Each file must have a corresponding `DocumentationFile = "advanced/FileName.md"` property on the endpoint's `[EndpointDescription]` attribute in the service class.

These files are markdown, not HTML, because the generator's DocumentationFile mechanism (see below) requires it - this is a fixed, mechanical convention, not a style choice, and it does not follow the general HTML-over-markdown documentation preference used elsewhere in this codebase. This system is entirely local to this repository, served from BaBackOffice.Web/EndpointDocumentation - it has no connection to Confluence and nothing here publishes to Confluence. Advanced documentation is optional; an endpoint does not require one. When a file is added, the endpoint's [EndpointDescription(...)] attribute must be decorated with the DocumentationFile parameter to specify it - otherwise the generator will not recognize the file, and it will be deleted on the next build as an orphan (see cleanup behavior above).

## Registering a file

Creating a file in this folder is not enough. The endpoint must declare it:

```
[EndpointDescription("...", DocumentationFile = "advanced/{Service}.{Name}.md")]
```

Endpoints are declarative - an endpoint declares its own advanced documentation. A file the generator does not find a matching declaration for is deleted on the next build. This is deliberate: it protects against drift when an endpoint is renamed, removed, or its DocumentationFile declaration is dropped, so an orphaned hand-written file never sits here describing something that no longer exists. README.md is the only file exempt from this cleanup.

If the attribute names a file that does not exist, the build fails. The generator throws an error naming the endpoint and the declared path, in this shape:

```
Endpoint '{Service}.{Name}' declares DocumentationFile '{declared path}' but no file exists at '{full path}'.
```

The file must exist before the declaration is added.

## What belongs here

Advanced documents do not define shape. They tell you how to use an endpoint.

Put in an advanced document:
- How to use the endpoint.
- Any special notes or considerations.
- An example.
- A facet of the shape, only when there is something about it that should be known or is tricky. Describe that facet and why it matters. Do not restate the whole type.

Never put in an advanced document:
- Shape that the generated documentation already provides: request or response type definitions, property tables or lists, parameter tables, method signatures, TypeScript or C# type blocks. That comes from the generated docs/ JSON and the MCP server's endpoint type-shapes tool.
- Anything generated or copied from generated output.
- Customer firm names or ids.

## Samples

- **[SecureApi.SaveClaim.md](SecureApi.SaveClaim.md)** - Write endpoint with complex business rules (staff, contacts, ad hoc fields, privacy, concurrency)
- **[SecureApi.GetAdvancedSearchResults.md](SecureApi.GetAdvancedSearchResults.md)** - Read endpoint returning structured search results with column definitions
- **[SecureApi.GetClaimContacts.md](SecureApi.GetClaimContacts.md)** - Read endpoint returning nested child data (contacts with ad hoc fields)
- **[SecureApi.SearchContactsByContactNameAndAKA.md](SecureApi.SearchContactsByContactNameAndAKA.md)** - Async parallel search with deduplication and wildcard matching

## Parent folder (EndpointDocumentation/)

The other items in `EndpointDocumentation/` (`docs/`, `index.json`, `openapi.json`) are **dynamically generated** and ignored in SVN. Do not manually edit those files as they will be overwritten.