Oq: Terminal OpenAPI Spec Viewer

Nice, I'll find this useful. I reference OpenAPI specs frequently as I practice spec-driven development. The spec is my source of truth for the interface, and I use it to generate both my client and server code. It automates all the request handling boilerplate on both sides, including validation, and provides me a typed interface regardless of which language I'm using. OpenAPI of course limits the types of endpoints you can create, but I find those limits stop you doing things that are strange/surprising. I find that creating APIs that can be expressed nicely in OpenAPI leads to APIs that have a consistent feel with few gotchas and a satisfyingly predictable developer experience.

Re: Oq: Terminal OpenAPI Spec Viewer

#6

Post by der_gopher » Fri, Sep 12, 2025, 6:39 PM UTC

oulipo2 wrote: post #3

Really cool! would be cool to be able to do the actual call too :)

I believe it will come to that too.

Re: Oq: Terminal OpenAPI Spec Viewer

#7

Post by der_gopher » Fri, Sep 12, 2025, 6:40 PM UTC

RadiozRadioz wrote: post #5

Nice, I'll find this useful. I reference OpenAPI specs frequently as I practice spec-driven development. The spec is my source of truth for the interface, and I use it to generate both my client and server code. It automates all the request handling boilerplate on both sides, including validation, and provides me a typed interface regardless of which language I'm using. OpenAPI of course limits the types of endpoints…

100%, also openapi specs are usually huge yaml/json files and it's very hard to navigate them.

Re: Oq: Terminal OpenAPI Spec Viewer

#8

Post by jamietanna » Fri, Sep 12, 2025, 6:52 PM UTC

Ooh interesting!

I see it notes OpenAPI 3.1 support, but it's using kin-openapi which doesn't yet support OpenAPI - how have you managed that?

(speaking as someone building on top of kin-openapi, as a core maintainer for oapi-codegen)

Re: Oq: Terminal OpenAPI Spec Viewer

#9

Post by der_gopher » Fri, Sep 12, 2025, 7:06 PM UTC

jamietanna wrote: post #8

Ooh interesting! I see it notes OpenAPI 3.1 support, but it's using kin-openapi which doesn't yet support OpenAPI - how have you managed that? (speaking as someone building on top of kin-openapi, as a core maintainer for oapi-codegen)

Hi Jamie, I've been a big fan of oapi-codegen and your work! I haven't fully tested the 3.1 support yet, but the tool doesn't do much, just list of routes and components, which I believe are similar between 3.0 and 3.1 OAS

Re: Oq: Terminal OpenAPI Spec Viewer

#10

Post by barryoneill » Fri, Sep 12, 2025, 7:09 PM UTC

Nice! Just a quick heads up that there's already an 'oq' project

https://blacksmoke16.github.io/oq/ | https://github.com/Blacksmoke16/oq

(as I discovered when I installed oq via homebrew to find myself with a different app)