Author Archives:
Add OpenAI flags to OpenAPI descriptions
x-openai-isConsequential
that you can add to your OpenAPI description, to indicate which endpoints should not be called without a human confirmation step.
I’m not doing much with OpenAI right now, but I do plenty with OpenAPI and the question “how do I add this field to my existing API description?” is one that I can answer! What’s more, you can use the advice in this post to add other extensions or additions to your OpenAPI descriptions using Overlays, this advice isn’t OpenAI-specific, but it’s used in the examples. Continue reading
When to version bump your OpenAPI description
API docs previews with Redoc and Netlify
Selective prose linting with Vale’s glob switch
I ran into one challenge though where I didn’t want to enable Vale for everything: a large internal documentation repo. This is the catch-all of things we should share with one another and like most internal company documentation sites, there is a lot going on. I assembled a very minimal set of Vale rules and still the first pass netted me over 10k errors. Luckily, Vale has a --glob
option, but it took me a while to find how to exclude multiple files and directories using it, so here’s the example for future-me, and anyone else who needs to see it! Continue reading
Visualise OpenAPI with Blockly
Tips for better documentation with OpenAPI
Raising the Next Generation of DevRel
As an individual contributor, manager and general DevRel presence over the years, I’ve developed some tactics both for myself and my team, and I’d like to share them in case they’re useful to others. Also since I’m moving to a less DevRel role, writing this down while I can still think about it! Continue reading
Improve Existing OpenAPI Descriptions
I also live in the real world, where OpenAPI descriptions get generated from existing codebases, and engineering teams lack either the knowledge or the enthusiasm to modernise their processes. With a generated OpenAPI description, everything else that OpenAPI enables is likely to be disappointing, because the description only contains the information that was in the serverside code, and if you’re lucky some comment metadata. Enter OpenAPI Overlays, a way to describe alterations to an existing OpenAPI description that can be reapplied every time that description changes. Continue reading