16 stories
Every team evaluating Model Context Protocol (MCP) servers reaches the same question: do we hand-maintain a second description of our API for agents, or do we generate it from the contract we already have? If you keep an OpenAPI document, the second answer is the sane one.
AI agents now read your API docs before developers do. What OpenAPI, llms.txt, Markdown pages, and an MCP server each give an agent, which one to build first, how to write descriptions an agent can act on, and how to keep all of them in sync with the code.
We fetched 1,927 public OpenAPI specs again and compared each with its 2023 copy. About half had changed, and nine in ten breaking changes had no new major.
Repo or hosted is the wrong question. What decides whether your API has one contract or several is which copy the others derive from, and who runs that step.
Swagger Editor, SwaggerHub, Stoplight's tooling, Postman Spec Hub, Insomnia, Apidog, and Redocly all edit an API spec, but they start from different inputs and stop at different points. A researched map of each, sourced.
Most style guides fail with too many rules, not too few. The work is deciding which rules stop a build, which leave a note, and which you will never enforce.
Most API doc platforms assume you already have an OpenAPI file. A researched map of what actually produces a reference doc when you don't: collection imports, AI write-ups, traffic discovery, and code-derived catalogs.
A researched map of how AI agents and the teams building them find and call APIs at scale outside of MCP: public marketplaces, unified-API platforms, and OpenAPI-driven agent tool generation, and where each one stops short of governing who gets to call what.
A precise map of the tools people reach for to keep an API contract true without hand-writing one: schema-first frameworks, code-reading generators, contract testing, and drift detection, and where each one actually stops.
Four working ways to get an OpenAPI 3.1 spec out of a codebase that never had one, what each approach misses, and how to keep the result true.
A linter flags a missing description, not a useless one, and the useless one is what an agent chokes on. What to write, what to leave out, and how to test it.
The Postman migration everyone postpones is mostly mechanical, and that is agent work. How an AI over MCP imports collections and rebuilds your assertions.
Every API contract decays once nothing enforces it. The four ways specs drift, why code generation does not save you, and how to make the spec true again.
How a tennis app’s REST API became an MCP server, which workflows moved into conversation, and why validation and permissions stayed in the app.
Two workflows for building APIs, and why the order you write the contract in changes everything downstream, from parallel work and review quality to drift.
Static analysis, framework fingerprints, and the messy middle where code and spec disagree.
Showing 16 of 16 stories
You're all caught up.
Get the top AI news and tools straight to your inbox every week.
Weekly · AI news
Join 15,000+ AI enthusiasts
