MOmooreds·Jul 5, 2026Submission
2 points · Open discussionOAI
OpenAPI-Specification
Markdown2014–2026
OAI / OpenAPI-Specification
OpenAPI-Specification
The OpenAPI Specification Repository
35Distinct people
40Mentions
1Explicit recommenders
31.3KGitHub stars
What to know before exploring
What it is
The OpenAPI Specification Repository
GitHub
Where it is used
No documented product use was verified in the last source check.
What people are saying
Yep. OpenAPI spec is not rich enough to represent relations like this so its rubbish for FE dev to use to generate models/api client. In general, the tooling/spec has thousands…
adamscybot used a recommendation phrase. One indexed comment matches. This is a phrase match, not a verdict.
No classified warning is attached to this page. Read the discussions before treating silence as approval.
Also in these discussions
- openapitools/openapi-generator · linked in 2 of the same discussions
- swagger-api/swagger-codegen · linked in 2 of the same discussions
Mentioned in the same Hacker News threads. That is not proof they are substitutes.
This week on Hacker News
Nov 7–Nov 14 UTC · Direct repository links and separately labeled related project stories. Indexed through 11/14/2026, 12:54:37 PM UTC.
No direct repository links were found in the indexed HN discussions over the past seven days. Older discussions are available below.
Mentions over time
HN mentions by year40 dated mentions
Observed mentions: 2014-03-21 01:41:57 UTC to 2026-07-05 14:59:36 UTC.
* An incomplete calendar period is marked with an outlined bar. Its count is not directly comparable with a full period.
Counts come from the repository’s dated source evidence. Index cutoff: 2026-11-02 08:16:59 UTC.
View mention counts and date ranges
| Period | Start (UTC) | End (exclusive, UTC) | Mentions | Submissions | Comments |
|---|---|---|---|---|---|
| 2014 | 2014-01-01 00:00:00 UTC | 2015-01-01 00:00:00 UTC | 4 | 1 | 3 |
| 2015 | 2015-01-01 00:00:00 UTC | 2016-01-01 00:00:00 UTC | 5 | 1 | 4 |
| 2016 | 2016-01-01 00:00:00 UTC | 2017-01-01 00:00:00 UTC | 5 | 0 | 5 |
| 2017 | 2017-01-01 00:00:00 UTC | 2018-01-01 00:00:00 UTC | 6 | 2 | 4 |
| 2018 | 2018-01-01 00:00:00 UTC | 2019-01-01 00:00:00 UTC | 0 | 0 | 0 |
| 2019 | 2019-01-01 00:00:00 UTC | 2020-01-01 00:00:00 UTC | 3 | 1 | 2 |
| 2020 | 2020-01-01 00:00:00 UTC | 2021-01-01 00:00:00 UTC | 6 | 2 | 4 |
| 2021 | 2021-01-01 00:00:00 UTC | 2022-01-01 00:00:00 UTC | 1 | 0 | 1 |
| 2022 | 2022-01-01 00:00:00 UTC | 2023-01-01 00:00:00 UTC | 5 | 1 | 4 |
| 2023 | 2023-01-01 00:00:00 UTC | 2024-01-01 00:00:00 UTC | 2 | 0 | 2 |
| 2024 | 2024-01-01 00:00:00 UTC | 2025-01-01 00:00:00 UTC | 1 | 1 | 0 |
| 2025 | 2025-01-01 00:00:00 UTC | 2026-01-01 00:00:00 UTC | 1 | 0 | 1 |
| 2026 (partial) | 2026-01-01 00:00:00 UTC | 2027-01-01 00:00:00 UTC | 1 | 1 | 0 |
What Hacker News says
40 sourcesReferring to OpenAPI: https://github.com/OAI/OpenAPI-Specification
In Show HN: A Fast HTTP Request CLI Powered by HTTLI fail to see how running something like protoc before running or compiling code is a show stopper. There are even npm packages that will install protoc for you [1]. That means you can use it in a custom npm build script action, or invoke it before staring the dev server? Put in a git pre-commit to run it to assert there are no changes? Run via a file-watcher?
IMO writing a schema in something like JSON for OpenAPI is way more verbose and time consuming than writing a proto file and a script or Makefile to invoke protoc. There also is the mismatch in capabilities. The JS-adjacent schema standards mostly do not directly support native types like uint64, let alone directly specify how to encode numbers like fixed64. I mean, look... the work around in JavaScript still is use "string" [2].
On the other hand, there is a standard in OpenAPI for
Read the rest
validating values. But that doesn't make sense in the Protobuf world since usually the API is expected to be forward and backward compatible, within reason, so something like a min and max value needs to be done at runtime, and not fixed within the schema. And don't get me started on trying to define cross-field validation in a declarative schema. It is easier to just write the code. :-)
So, IMO, no, a single standard won't happen in the industry. The many dimensions like logical vs physical models, validation, or error handling that make it impossible.
[1] https://www.npmjs.com/package/@protobuf-ts/protoc
[2] https://github.com/OAI/OpenAPI-Specification/issues/2617#iss...
I saw your sibling comment about "keeping it simple," however that is a bit counter to "generates OpenAPI specifications" since those for sure are not limited to just application/json request/response bodies
I wanted to draw your attention to "normal" POST application/x-www-form-urlencoded <https://github.com/OAI/OpenAPI-Specification/blob/3.1.0/vers...> and its multipart/form-data friend <https://github.com/OAI/OpenAPI-Specification/blob/3.1.0/vers...>
The latter is likely problematic, but the former is in wide use still, including, strangely enough, the AWS API, although some of their newer services do have an application/json protocol
I know that's a lot of words, but the tl;dr would be that if you want your extension to be application/json only, then changing the description to say "OpenAPI specifications for application/json handshak
Read the rest
es" would help the consumer be on the same page with your goals
I prefer reading proto files with services over OpenAPI yaml. Here's the pet store example to compare.
- https://github.com/project-flogo/grpc/blob/master/proto/grpc...
- https://github.com/OAI/OpenAPI-Specification/blob/main/examp...
In Protobuf-ES: Protocol Buffers TypeScript/JavaScript runtimeAsk HN: Non-Breaking API deprecation in OpenAPI spec – what do you think?
Sometimes APIs need to be retired, for example when they are superseded by a new version.
OpenAPI specification supports a "deprecated" flag which can be used to mark operations and other object types as deprecated, but it lacks the ability to manage a 2-phased API retirement process:
1. Deprecate an API and, optionally, announce a "sunset" date
2. Delete the API at the sunset date or later
People seem to want such a process in order to prevent breaking-changes.
I wrote a diff tool for OpenAPI spec which supports detection of breaking-changes and I recently extended it to support this process and a bit more.
Now I'm looking for feedback.
Proposed Solution (currently in Beta): https://github.com/Tufin/oasdiff#non-breaking-removal-of-deprecated-resources
Related requests:
1. https://github.com/Tufin/oasdiff/issues/116
2. https://github.com/
Read the rest
OAI/OpenAPI-Specification/discussions/2770
Your feedback is much appreciated!
> JSON has no namespaces
Causing all extensible JSON-based protocols to eventually reinvent them:
* https://www.w3.org/TR/json-ld11/#compact-iris
* "If new events are added, the event type key SHOULD follow the Java package naming convention, e.g. com.example.myapp.event." https://spec.matrix.org/v1.2/client-server-api/#types-of-roo...
* https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-22... (no aliases, so it's even more verbose)
* https://github.com/OAI/OpenAPI-Specification/issues/1362#iss...
In Is XMPP any good? Also, let's write a client in Tcl, maybe100% onboard with better tooling.
Starting with out of the box swagger support: https://github.com/OAI/OpenAPI-Specification/issues/396
Shame they are not interested in adding it.
In HTTP FeedsSometimes smooth, sometimes not so.
We use FETCH/HTTP and STOMP/WS to move the data, the main issue has always been spotty communication inside the team. A while ago, the situation was even worse, so some progress did happen. OpenAPI annotations to generate Swagger docs helped a bit, but I rarely bother to open these. Drafting endpoint signatures in TypeScript as a part of our workflow yielded great results, something concrete to talk about when things don't work as expected or during code reviews. Unfortunately, the agreements are as good as initial requirements, if the team does not understand or communicate these clearly, misunderstands are bound to happen. The other pain point is that OpenAPI only supports HTTP (https://github.com/OAI/OpenAPI-Specification/issues/55), there's no documentation for STOMP endpoints and custom RPC run ove
Read the rest
r it. Another thing is when signatures change unexpectedly (I know, this should never happen; at least integration tests help here) in subtle ways and the UI suddenly starts misbehaving; types shared between frontend (TypeScript) and backend (Java) can partially alleviate the issue, but none of available tools provide what I'd really like to use, the results are either not expressive enough (no ADTs, unlike types authored by hand) or really hard to reconcile with existing code base.
Yep. OpenAPI spec is not rich enough to represent relations like this so its rubbish for FE dev to use to generate models/api client.
In general, the tooling/spec has thousands of open bugs, isnt going anywhere, moves very slowly and is missing fundamental features.
https://github.com/OAI/OpenAPI-Specification/issues/1998 heres the ticket where it will inevitably be ignored and die. But even if it was supported in the spec, the open source generators wont support it anyways.
Said generators also uses "logic less" templates to generate something that very much needs logic. As a FE dev, I love nothing more than to fork a an archaic Java based generator to get the client gen working...not.
In Best practices for REST API design (2020)Are there any examples of "programs as databases" being applied to structured text like JSON or YAML? Something like a generic system which takes a set of rules/facts and the source data, and transforms these into a queryable data structure.
I'm working with a lot of OpenAPI [1] specifications currently, some of which span tens of thousands of lines. Heaps of parent, child, sibling type relationships, and objects which are defined-once and referenced in many places. It would be nice if I could perform a search like "select all schemas used in this path" or "select the count of references to this parameter".
[1] https://github.com/OAI/OpenAPI-Specification/blob/master/ver...
In Turning the IDE Inside Out with DatalogLet me preface this by saying that I use OAS because it is the most widely-supported HTTP API spec. I don't love it, but as of version 3, it handles all of my use cases and has good tooling support. This prevents me from having to edit the spec as raw text -- I can typically get by using a GUI (recently been happy with Apicurio Studio).
That said, I do wish there were a better format for it than YAML/JSON, and I think some of their design decisions were strange.
Note that a lot of OAS's strengths and weaknesses were inherited from its parent project, JSON Schema, which is also widely supported.
> I wanted it to be a terse specification, such that just glancing over the definition file gives you a sense of what the API consists of.
OAS specs in YAML (as opposed to JSON) are pretty terse and easy to scan, especially if the spec is kept fair
Read the rest
ly DRY by defining/refusing object schemas.
> I wanted a solution that handled websockets/server push as a first-class citizen, and not as a secondary add-on
OAS fails this one.[1]
> I wanted to provide library-level validation of request / response shape.
This is something all the major formats (JSON Schema/OAS, RAML, Blueprint, etc.) do. It's probably the first thing people want to do with an API spec. OAS has great support for validation in most languages, although implementation of the spec can be spottier with less-popular stacks like PHP.
> I wanted to extend it beyond typescript, notably into python (and hopefully beyond)
One of my projects uses Spot[1] to define its API. Spot has CLI tools that translate it into a plain OAS file (.yaml format), and then there are more CLI tools that generate code (models, validators, controllers, and even servers) from that spec file.
If you don't mind a polyglot toolchain -- and I think most of us have one at this point -- then the Spot => OAS => Python process works fine and is easy to set up. You don't even need to start with Spot, of course.
> I like the idea of generic structs and oneofs (which I'm going to implement in some future version). I think if we had an easy way to define generics in cross-language APIs, we'd probably use it a fair amount.
I agree that this is super important. OAS supports it, although it can be hard to read a lot of branches inheritance trees in that particular format.
You can split your definitions into separate files to make it easier (in both Spot and in plain OAS itself).
> I like the idea of having an extensible language, e.g. be able to provide a JSONLogic type. Imagine a field `priceCalculation: JsonLogic<string, number>`. That'd be pretty cool!
This makes sense, but at the end of the day, "JsonLogic<string, number>" is just a text format. With OAS, you can define a regex to validate inputs and outputs, which has been "good enough" in my experience, but definitely falls short of what you want.
What about GraphQL? That seems to have some of the features you're interested in, although the GraphQL paradigm is so different from HTTP (and has some tradeoffs) that I'd understand not even considering it.
1. https://github.com/OAI/OpenAPI-Specification/issues/523
> leads to projects not using anything at all
We're counting that against products when we're analyzing what services to adopt/purchase. You doing nothing at all ... or something non-standard results in everyone else having to attempt to do it for you with the resulting inconsistencies. I'm not sure why you think OpenAPI is tailored for XML ... Here's the specification for the sample application (petstore) with service and model definitions in YAML - https://github.com/OAI/OpenAPI-Specification/blob/master/exa....
In Show HN: Verify JSON using minimal schemaI would love if the definition of websockets would be added to OpenAPI https://github.com/OAI/OpenAPI-Specification/issues/523
In AsyncAPI – OpenAPI-like specification for event-driven architecturesShowing the 15 most recent of 40 sources. Enable JavaScript to search and browse every indexed mention.