Notes on CLI UX

· 2 min read
NotesCLIGoOpenAPI

As part of the Beyond the Docs project, I’ve been working on building a new Django REST API. I decided to build an OAS file for the API and use SpecGate to test it. The OAS had structural issues, so SpecGate’s validation logic rejected it entirely:

if err := doc.Validate(loader.Context); err != nil {
  fmt.Fprintf(os.Stderr, "specgate: spec validation failed: %v\n", err)
	os.Exit(2)
}

So if the OAS has any structural issues, SpecGate will report the error and exit. So you don’t even get to see what the issues are. And that’s a problem. I spent way too much time trying to figure out how to fix my OAS file.

Yes, the OAS file should be structurally sound. This is important. But the question I had to ask myself was how important this was for SpecGate. If the file isn’t structurally sound (according to kinapi’s Validate method), users won’t be able to see what’s missing from the file. They can’t get past the first gate.

So I decided to soften the validation logic for the check command. SpecGate still checks for structural integrity, but if it finds issues, the issues are written to a .log file.

if err := doc.Validate(loader.Context); err != nil {
  issuesFile, _ := os.Create(".specgate.log")
  if issuesFile != nil {
    fmt.Fprintf(issuesFile, "OpenAPI Structural Issues\n")
    fmt.Fprintf(issuesFile, "=========================\n\n")
    fmt.Fprintf(issuesFile, "%v\n", err)
    issuesFile.Close()
    }
}

This way, if users are interested, they can see the details of the structural issues and fix them (or not).

What I take away from this is that good UX design is about reducing friction. Rather than block users on those structural issues, I can give them visibility into those issues instead, and they can review them on their own.

I think I may do more digging into UX patterns for CLIs.

All articles