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.<--more-->

The script:

#!/usr/bin/env -S uv run --script

# /// script
# requires-python = ">=3.11"
# dependencies = [
#   "argparse",
# ]
# ///

import glob
import subprocess
import random

port = random.randint(0,500) + 3000;

# Add your own fudge/expansion magic here if you have APIs to find
path = f'../api-*/oas/*.oas.yaml' 
url = f'http://localhost:{port}'

files =  glob.glob(path)
if len(files) > 0:
  for f in files: # works for one match
    # copy URL to clipboard for convenience
    subprocess.run(["pbcopy"], input=url, text=True)
    subprocess.run(["scalar", "document", "serve", "-p", str(port), f])
else:
  print("API not found");

I’m using Python and I run this script with uv because I run this script from lots of different folders and it takes care of dependencies so neatly (confession: my actual script uses argparse and some inputs to feed the “guess the location of the API file from these three digits” magic but that part probably isn’t useful to other people!)

First I generate a random port number and use it to construct a URL – there’s no checking that the port is available but given that I rarely have more than 4 or 5 of these up at one time, it rarely collides and I just run the script again if it does!

The subprocess calls then run the commands I would actually run myself on the commandline if I didn’t use a script to generate a random port number and do some path fudging logic for me:

  • `pbcopy http://localhost:3333` (run this command first because the next one blocks)
  • scalar document serve -p 3333 openapi.yaml

Then I have the URL and can paste it into my browser. You could just open a browser tab instead of copying but I find it always picks the wrong tab/window/app/whatever so in my clipboard is more useful to me. I also use a clipboard history tool so it isn’t a problem to have lots of things writing to my copy buffer.

Feel free to adapt the script to fit your own paths and preferred tools; probably some of you do this often enough that it’s worth having a wrapper rather than remembering the correct incantation or relying on a hosted platform to download and upload to when the file is already local. And as always, if you do something differently, I’d love to hear about it!

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

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

Checking Links in Docs-As-Code Projects

Creating content requires accuracy as well as creativity and the ability to deliver. Working with docs-as-code gives a strong foundation and structure to work within, and means there’s a clear workflow where automation can be added to help us with the easy stuff, such as “do all these links work?”.

I really appreciate having the extra confidence and support of these types of tools, and having implemented them on multiple projects at this point, I thought I’d share my advice for anyone looking to do the same. Continue reading

Reviewdog filter settings with GitHub Actions

Reviewdog is a tool to use with GitHub actions for applying review tools in your CI. I use it with Vale, and it’s really good. One thing that has tripped me up multiple times is that by default, it only applies the checks to the changes in the pull request, not to the whole project. So when you add something like Vale, which is a prose linter, it only checks … the workflow file you just added! I always forget that it works this way, and how to change it, so I’m pasting some examples for future reference. Continue reading

Add OpenAI flags to OpenAPI descriptions

With OpenAI’s new Actions feature allowing you to get a GPT that uses your own API, many new doors are open. However giving an AI an access token the keys to your API and telling it to have fun may lead you to realise that one of the doors available leads to the empty lift shaft of overwritten data, or the bottomless well of cloud bill shock. To reduce the risks, OpenAI supports an extension 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

I’ve heard a variety of bad advice (and some untruths!) regarding how to version your OpenAPI description lately. Rather than dig into those, instead I’ll share my opinion on how I like to version API descriptions in my own projects. Every API project is different, but perhaps there’s something here that can help your project too. Continue reading

Manager’s Secret Second Calendar

Employees expect a lot from their managers, and as managers we do our best to meet those expectations. However most managers are only human (I’ve met a few that I had doubts about), and so it can be difficult to get absolutely everything right absolutely all the time. I’d like to share a tactic that I learned from another manager around the time that I took my first line manager role, that I think really helped me to at least give the impression that I knew what was going on: a second calendar, visible only to you, with key dates in. Continue reading

Who are you writing that commit message for?

I read a lot of commit messages that make me wonder who the committer had in mind when they wrote it. If you don’t read commit messages yourself, I think that can make it even more difficult to think about who the audience is, or when someone would be reading those entries. Perhaps you’re writing for nobody, or work in a team that doesn’t value the metadata that a single sentence written in the moment can deliver.

Next time you write a commit message, try some of these suggestions as your imaginary audience:

  • Yourself, next week, when you finally get back to working on this thing and can’t remember where you were up to
  • Yourself, when you get a pull request review and can’t remember which commit something is in that needs to be removed
  • Yourself, debugging how this ended up like this, 6 months from now
  • Your colleague, eyeballing your work to see how you are getting on

Personally, I think of it as a note to myself. Like an alibi, if someone asks you what’s already been done, or what this commit that removes one specific line from a long config file. Yes, I worked as a git consultant for a while, the delete-a-single-line with the commit message “Fixed” is always the culprit!

Further reading: https://cbea.ms/git-commit/

VSCode setup for technical writers

I’m working almost entirely with docs-as-code setups for prose at work these days and while I do use vim for most of what I do, VSCode is increasingly in the mix. It’s just about accessible enough with keyboard shortcuts and the command palette for me, and I thought I’d share the extensions I’m using and find helpful. Continue reading