Tag Archives: tips

29 Jun
2026

Using mitmproxy reverse mode for API testing

mitmproxy is my preferred proxy for API testing these days. I’m using it mostly in reverse mode though, so I thought I’d capture my setup in case it’s useful for anyone else. My main use case is to inspect the traffic coming into the API server and being returned, mostly when running tests against it. Where mitmproxy is typically used as a proxy to monitor traffic passing into/out of a client application, for this I’m concerned with the server’s handling. Reverse mode lets me inspect and adjust the traffic as I go along. I start up the proxy, configure the tests to point to it instead of the actual server, and I’m all set. Continue reading →
04 Mar
2026

Selectively ignore lines in git diff

I have a things-as-code project that outputs mostly text-based formats, but a lot of them. To keep an eye on consistency, I rebuild all the outputs and dump them into a local git repository so I can very easily diff to spot any changes – which was fine until we added a build timestamp, so every file looks changed on every run! This post is about ignoring the matching line with git diff -I. Continue reading →
28 Jan
2026

Git renames are not renames

I consider myself pretty git-confident, I’ve worked with it a lot, taught it, been a git consultant, run engineering and various things-as-code teams. This week I had a spectactular git problem where merging one branch into another produced changes that didn’t exist on either branch. Turns out, renaming directories in a monorepo with multiple almost-identical boilerplate documentation files comes with surprises… Continue reading →
25 Jan
2026

Manage Diagrams in AsciiDoc on GitHub

I use a lot of asciidoc these days for work documentation (and I love it) and I’ve been so happy that GitHub renders it when you view a repository in the web browser, just like it does for Markdown and ReStructuredText. BUT what GitHub does not do is render the image types that asciidoc does so even though I’m working with asciidoc and PlantUML, and the asciidoc tools render those diagrams nicely in PDF and HTML output – GitHub’s rendering doesn’t. So here’s a quick overview of how I handle those repositories. Continue reading →
08 Dec
2025

Tag Kinds in OpenAPI 3.2

OpenAPI tags have always been annoying: user-supplied arbitrary data for endpoints should be a fabulous feature – but the documentation tools seem to think that tags are only for them so it becomes more difficult to use tags for other purposes. In fact it is very useful to be able to tag endpoints with lots of different categories of data and so in OpenAPI 3.2, tags were enhanced to include an additional “kind” field so that different kinds of tag could be used. Continue reading →
04 Dec
2025

Nested tags in OpenAPI 3.2

OpenAPI has always had support for simple tags, but the OpenAPI 3.2 release brought in some serious tag upgrades including a summary field, a “kind” field with registry, – and the ability to nest tags which is the focus of today’s post. If one level of organisation isn’t enough for your API (and on bigger APIs I’d argue it shouldn’t be) then the ability to indicate which tag is the parent of this tag will be a good feature to adopt when you upgrade your OpenAPI descriptions. Continue reading →
16 Nov
2025

Notification Contexts Matter

Like many of you, my days are dominated by notifications. Emails from project management systems, source control systems, calendar invitations, ticket updates, and message about messages on other platforms. I’ve noticed that some people use notifications as a power tool, while others seem blind to what happens when they do something. So this post is some tips that I’ve picked up along the way. Continue reading →
17 Sep
2025

Quick local API docs with Scalar

Today I’m sharing a quick-and-dirty script to take an OpenAPI description, spin up a docs server locally, and copy the URL into your clipboard. I also use a bit of glob expansion in my script to find the right folder, because I have a lot of APIs with long and formulaic directory names (TM Forum members know this story). I’m spinning up Scalar here as it’s my current favourite just-works local API docs platform. Continue reading →
28 Apr
2025

Just Enough Docs

Too many open source projects suffer from inadequate documentation, and that hurts their adoption, their communities, and puts more burden on maintainers. Many people who create open source software don’t see see themselves as writers, but today I’m sharing tips for documenting open source projects without it needing to take up a huge amount of time to get something published and ready for (docs) contributions. Continue reading →
09 Jan
2025

Save edits to OpenAPI as an Overlay

For teams that generate OpenAPI from their codebase, there’s a tough choice between maintaining rich and extensive content such as Markdown descriptions and examples in codebase annotations, or in making those changes to the generated file – and then losing them when the code changes and the file is regenerated. The new OpenAPI Overlay Specification defines a format for storing updates to an OpenAPI document, and there’s a new generation of tools to make it easy to do, so let’s take a look. Continue reading →