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
8 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…
6 Feb 2022
This is Part III of a multi-part series. Below are the links to other parts of this tutorial! OpenAPI Tutorial Part I: Introduction to OpenAPI OpenAPI Tutorial Part II: Common API Example OpenAPI Tutorial Part III: Paths and Basic Request Data The end result of this article can be found at jtreminio/openapi-tutorial branch “part-iii”. You can clone it by doing…
5 Feb 2022
This is Part II of a multi-part series. Below are the links to other parts of this tutorial! OpenAPI Tutorial Part I: Introduction to OpenAPI OpenAPI Tutorial Part II: Common API Example OpenAPI Tutorial Part III: Paths and Basic Request Data In the first part of this series we lightly touched on the differences between Swagger and OpenAPI mentioned some…
31 Jan 2022
This is Part I of a multi-part series. Below are the links to other parts of this tutorial! OpenAPI Tutorial Part I: Introduction to OpenAPI OpenAPI Tutorial Part II: Common API Example OpenAPI Tutorial Part III: Paths and Basic Request Data The end result of this article can be found at jtreminio/openapi-tutorial branch “part-i”. You can clone it by doing…
15 Feb 2019
As part of my work on standards under GA4GH, I frequently deal with API specifications, most often written in OpenAPI 3 (OAS 3). The setup is always similar – there’s a public GitHub repository containing an OAS 3 YAML file and a few common auxiliary files (.gitignore, LICENSE, CONTRIBUTING.md, and README.md). Reference implementations of...