Extending an OpenAPI Component Schema

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: https://example.com/probs/out-of-credit title: type: string description: A short, human-readable summary of the problem type example: You… continue reading.

Posted on 26 August 2025 in OpenAPI Leave a comment

Using OneOf for a property in an OpenAPI spec

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 curl: curl -X "POST" "http://api.example.com/pets" \ -H 'Content-Type: application/json' \ -d $'{ "name": "Rover", "items": [… continue reading.

Posted on 13 May 2025 in API, OpenAPI

Previewing OpenAPI specs using redocly's Docker container

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 a dev is running an older (or newer!) version of Node. For OpenAPI specs, listing… continue reading.

Posted on 22 April 2025 in API, Docker, OpenAPI

Category: OpenAPI