Oq: Terminal Openapi Spec Viewer

Posted4 months agoActive3 months ago

der_gopher

124 points

20 comments

github.comTechstory

supportivepositive

Debate

20/100

OpenapiAPI DevelopmentTerminal Tools

Key topics

Openapi

API Development

Terminal Tools

The post introduces 'oq', a terminal-based OpenAPI spec viewer, and the community responds with enthusiasm and suggestions for improvement.

Snapshot generated from the HN discussion

Discussion Activity

Active discussion

First comment

Peak period

Day 1

Avg / period

Comment distribution20 data points

Loading chart...

Based on 20 loaded comments

Key moments

01Story posted
Sep 12, 2025 at 10:53 AM EDT
4 months ago
Step 01
02First comment
Sep 12, 2025 at 1:15 PM EDT
2h after posting
Step 02
03Peak activity
16 comments in Day 1
Hottest window of the conversation
Step 03
04Latest activity
Sep 25, 2025 at 2:52 AM EDT
3 months ago
Step 04

Generating AI Summary...

Analyzing up to 500 comments to identify key contributors and discussion patterns

Discussion (20 comments)

Showing 20 comments

oulipo2

4 months ago

2 replies

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

thegagne

4 months ago

Check out https://aep.dev, they have a CLI tool for doing that, _if_ you write your OpenAPI to follow their spec. We are adopting it, both because of the nice standard it provides and also for the guaranteed tooling (TF, MCP, CLI).

der_gopherAuthor

4 months ago

I believe it will come to that too.

RadiozRadioz

4 months ago

2 replies

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.

thegagne

4 months ago

1 reply

What’s in your toolkit for server and client generation?

RadiozRadioz

4 months ago

My servers are Java, my clients are Python. I use the Spring & Python generators in https://github.com/swagger-api/swagger-codegen

der_gopherAuthor

4 months ago

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

jamietanna

4 months ago

3 replies

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)

der_gopherAuthor

4 months ago

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

der_gopherAuthor

4 months ago

libopenapi won :)

jamietanna

3 months ago

* doesn't yet support OpenAPI 3.1

barryoneill

4 months ago

1 reply

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)

der_gopherAuthor

4 months ago

1 reply

Yeah, the name is very short to be unique. I don't want to rename yet, as I am ok if there are other projects with the same name as long as there is no legal trademark or something. But yeah, don't install it from the Homebrew, btw I added binaries to releases page so we can just wget it.

mdaniel

4 months ago

1 reply

Two things: folks care about Brew because its update story is nice; otherwise one needs to constantly revisit your /releases (or plug /releases.atom into their RSS reader) in order to know. It also offers very light "I got what I expected" behavior via their use of sha256, which your current setup won't participate in since you're only publishing .md5 anyway

That leads to the second thing which is that you said you "added binaries" but your release artifacts are .tar.gz which means that one now needs to `curl -fSL | tar -xzf - -C /whatever` and deal with whatever interior directory scheme you are using (I didn't check)

I suspect I may be throwing good commentary after bad, but if you did want to participate in Brew distribution, but don't want to go through their stupid PR process, you can retain control over your update schedule by creating a "Brew Tap" and then the consumer would (e.g.) `brew tap plutov/brew && brew install plutov/brew/oq` which also gets away from the naming collision

der_gopherAuthor

4 months ago

1 reply

I also love Homebrew and use it daily, at the same time I don't want to go through the review process, but tap sounds good, will try it out, maybe goreleaser supports that too?

deltaknight

4 months ago

Honestly whilst the docs make the review process sound complicated, I went through it a few months ago and it ended up being super simple. Just follow the instructions to create the new formulae PR (and look at other recent ones) and then you’re all done. Updates are handled by a bot they run automatically when you make a new GitHub release, so you don’t even need to interact with the homebrew repo after setup.

You do have a naming conflict though unfortunately so I’m not sure how you would deal with that.

neiesc

4 months ago

Awesome

dot1x

4 months ago

Where's the search? Can't seem to search in any way.

rtk0

4 months ago

Love this.

patrickhogan1

4 months ago