I have a new project where we will be integrating with a third party API that is currently being written. Due to Conway's Law, we are being sent new versions of the OpenAPI spec as a set of JSON files via email. I quite like seeing the HTML rendering of an OpenAPI spec when reading it and understanding it, so…
#openapi
4 posts
17 Mar
26 Aug 2025
One project that I'm working on uses RFC 9457 Problem Details for HTTP APIs for its error responses. In the OpenAPI spec, we can define this as a component and use in the relevant paths as appropriate: components: schemas: ProblemDetails: type: object properties: type: type: string format: uri-reference description: A URI reference that identifies the problem type default: about:blank example:…
13 May 2025
When writing an OpenAPI specification, I came across the need for a particular property in an error response to be either a string or an object. This situation came about when validating a POST request that takes an items property that is a list of objects As a contrived example of a pet with accessories, consider this example request in…
22 Apr 2025
To provide consistency between the environments of our developers, I'm a strong proponent of using containers so that every developer is using the same versions of our tools. This is really important for command line tooling that depends on a separately installed language such as NodeJS or PHP as a simple npm i -g can install wildly different versions if…