docs

Custom Lint Rules and Decorators: Encoding Team Conventions in the Spec

Quick answer: Built-in linting catches generic mistakes, but every team has conventions that generic rules do not know, naming standards, required headers, versioning rules, and which operations an agent may

Read article →

Docs Search: Hosted Indexing vs Static Build-Time Search

Quick answer: Docs search is a core navigation feature, not an add-on, and the choice between a hosted search index and build-time static search is really a decision about infrastructure,

Read article →

Bundling Multi-File OpenAPI: $ref Resolution Compared

Quick answer: Splitting an OpenAPI document across files is the right move for large APIs, but every tool that consumes the spec — docs, mock servers, code generators, gateways — needs a

Read article →

Versioned Docs for Multiple API Versions: Mintlify vs Spec Branches

Quick answer: Versioned documentation is only worth its complexity if you actually support multiple live API versions; for a single evolving API, a well-managed deprecation policy with one current spec

Read article →