Topic
Quick answer: Webhooks and callbacks are HTTP requests your service makes, not ones it receives, and they deserve the same contract discipline as inbound operations. Define their payloads, signing, and
Read articleQuick answer: The readOnly and writeOnly keywords exist precisely so a generator can split one schema into the shape a client receives and the shape it sends. If your generated
Read articleQuick answer: A reliable API changelog is generated by diffing two versions of the OpenAPI spec and classifying each change as breaking, non-breaking, or a deprecation, rather than maintained by
Read articleQuick answer: Documentation stays accurate only when regeneration is wired into the same pipeline that changes the spec, not when it depends on a person remembering to rebuild the docs
Read articleQuick answer: For file uploads, multipart/form-data is the default correct choice because it streams binary bytes alongside other fields without inflating size, while a Base64 body is a workaround
Read articleQuick answer: A oneOf schema with a discriminator expresses a tagged union, and good generators turn it into a closed sum type you narrow by checking the tag, but a
Read articleQuick answer: Breaking API changes are rarely the result of someone intending to break clients; they are the result of a change that looks harmless in a pull request but
Read articleQuick answer: A static API reference tells a developer what an endpoint is, and an interactive playground lets them find out what it does, and the difference shows up the
Read articleQuick answer: Query parameters that are arrays or nested objects are one of the most common silent contract mismatches, because the OpenAPI name and type say nothing about how the
Read articleQuick answer: Most OpenAPI generators map format: date-time to a plain string rather than a real date object, which is convenient for the type system and dangerous for the application:
Read articleQuick 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 articleQuick 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