2 posts tagged with "OpenAPI"

An endpoint rarely stands alone. Creating a payment may require a customer, and its successful response may lead naturally to fetching, capturing, or refunding that payment. If those relationships exist only in prose, readers have to reconstruct the workflow themselves.

Speccy combines three complementary forms of operation relationship:

• OpenAPIOpenAPIA machine-readable standard for describing HTTP APIs, including their operations, parameters, request bodies, responses, and schemas. links describe what a caller can do after a particular response.
• x-speccy-prerequisites describes what must already have happened before the operation can be called.
• OpenAPIOpenAPIA machine-readable standard for describing HTTP APIs, including their operations, parameters, request bodies, responses, and schemas. callbacks describe requests the API may later send to the caller.

Together they give an operation a useful sense of place: what gets you here, where can you go next, and what might come back to you?

OpenAPIOpenAPIA machine-readable standard for describing HTTP APIs, including their operations, parameters, request bodies, responses, and schemas. is good at describing an API. Reading the result is often harder than it should be.

Large references become walls of expanding panels. Important context gets buried between schemas and examples. Teams work around the renderer in front of them, copying explanations into a second content system or accepting that their API documentation will always feel a little hostile.

Speccy is an OpenAPIOpenAPIA machine-readable standard for describing HTTP APIs, including their operations, parameters, request bodies, responses, and schemas. renderer built to make that contract easier to read, publish, and maintain. It keeps the specification as the source of truth and gives the content room to breathe.