OpenAPI v4 Proposal

This page summarizes the projects mentioned and recommended in the original post on news.ycombinator.com

Our great sponsors
  • SurveyJS - Open-Source JSON Form Builder to Create Dynamic Forms Right in Your App
  • WorkOS - The modern identity platform for B2B SaaS
  • InfluxDB - Power Real-Time Data Analytics at Scale
  • sig-moonwalk

    Version 4.x of the OpenAPI Specification is known as "Moonwalk," and has a goal to ship in 2024.

    One of the Moonwalk discussions is indeed about moving from objects to arrays for many structures: https://github.com/OAI/moonwalk/discussions/32

    Also, I agree with the person who mentioned JSON Patch (RFC 6902), which I feel is an under-rated and underused technology. While less intuitive than JSON Merge Patch (RFC 7396), it is far more powerful. I have used both together, using JSON Merge Patch where possible to keep things more readable and intuitive, and using JSON Patch where JSON Merge Patch can't do what is needed. Although if most of your changes need JSON Patch, I find it's better to just stick with that.

  • openapi-generator

    OpenAPI Generator allows generation of API client libraries (SDK generation), server stubs, documentation and configuration automatically given an OpenAPI Spec (v2, v3)

    I've tried using OpenAPI a few times, it's been...lackluster... I probably won't use it again.

    Here are my gripes:

    1) For me one of the biggest selling points is client code gen (https://github.com/OpenAPITools/openapi-generator). Basically it sucks, or at least it sucks in enough languages to spoil it. The value prop here is define the API once, code gen the client for Ruby, Python and Scala (or insert your languages here). Often there are a half dozen clients for each language, often they are simply broken (the generated code just straight up doesn't compile). Of the ones that do work, you get random PRs accepted that impose a completely different ideological approach to how the client works. It really seems like any PR is accepted with no overarching guidance.

    2) JSONSchema is too limited. We use it for a lot of things, but it just makes some things incredibly hard. This is compounded by the seemingly limitless number of version or drafts of the spec. If your goal is interop, which it probably is if you are using JSON, you have to go our and research what the lower common denominator draft spec JSONSchema support is for the various languages you want to use and limit yourself to that (probably draft 4, or draft 7).

  • SurveyJS

    Open-Source JSON Form Builder to Create Dynamic Forms Right in Your App. With SurveyJS form UI libraries, you can build and style forms in a fully-integrated drag & drop form builder, render them in your JS app, and store form submission data in any backend, inc. PHP, ASP.NET Core, and Node.js.

  • NSwag

    The Swagger/OpenAPI toolchain for .NET, ASP.NET Core and TypeScript.

    I find it odd that you've struggled so much with generating API clients. I've generated C# and TypeScript (Angular's HttpClient and React Query) clients for my API and never had any issues with them. With that being said, I didn't use OpenAPI's Java-based code generators and rather used ones made by third-party developers such as NSwag[0] and openapi-codegen[1].

    [0]: https://github.com/RicoSuter/NSwag

  • fern

    🌿 Stripe-level SDKs and Docs for your API

    I'm one of the builders of an open source project (buildwithfern.com) to improve client codegen. One of the learnings I've had is that the quality of OpenAPI specs varies widely (like really widely). We wrote a linter that suggests improvements to your OpenAPI before you run the code generators and that's been really helpful for generating idiomatic clients.

    You can try Fern for free: https://buildwithfern.com

  • openapi-codegen

    A tool for generating code base on an OpenAPI schema.

  • speakeasy

    Speakeasy CLI - Enterprise developer experience for your API (by speakeasy-api)

    I'm working on a company https://speakeasyapi.dev/ with the goal helping companies in this ecosystem get great production quality client sdks, terraform providers, cli(s) and all the developer surfaces you may want supported for our API. We also manage the spec and publishing workflow for you so all you have to do is build your API and we'll do the rest.

    Feel free to email me at sagar@speakeasyapi.dev or join our slack (https://join.slack.com/t/speakeasy-dev/shared_invite/zt-1cwb...) . We're in open beta and working with a few great companies already and we'd be happy for you to try out the platform for free!

  • redux-toolkit

    The official, opinionated, batteries-included toolset for efficient Redux development

    I've been using redux toolkit's OpenAPI code generator for a side project and it's been pretty good. The documentation is a bit lacking and it could certainly use more work to make names more customizable. The generated code comes out looking very much machine generated. But I love that RTKQuery (redux toolkit query) has client side caching so that if I use a query param that was already used before, it will remember and just serve from the local cache.

    But it's been nice being able to make a backend change, run the code generator, and then be able to use whatever API in react. I hope this type of stuff gets developed more!

    [0] - https://github.com/reduxjs/redux-toolkit/tree/master/package...

  • WorkOS

    The modern identity platform for B2B SaaS. The APIs are flexible and easy-to-use, supporting authentication, user identity, and complex enterprise features like SSO and SCIM provisioning.

  • spec

    The AsyncAPI specification allows you to create machine-readable definitions of your asynchronous APIs. (by asyncapi)

  • smolblog

    A blog engine for the social web. This is the monorepo that contains the PHP code for the project.

    I'm trying to go in this direction with an API I'm building at the moment in PHP: https://github.com/smolblog/smolblog-core/tree/feature/api-b... It uses a combination of definition-in-code (also used to translate the endpoint classes to the outside framework), reflection, and PHP annotations to generate the OpenAPI spec which I'm loading into Swagger to do testing.

  • swagger-typescript-api

    TypeScript API generator via Swagger scheme

    You said it yourself — the “official” generator is awful and very hard to modify or extend (well, you didn’t say that, but I’m saying it) and while there are many alternatives, they’re not always easy to find. I had some success with swagger-typescript-api[1], but eventually got tired of it and wrote my own generator. Despite looking around quite a bit at what’s available, I never heard of openapi-codegen, which looks quite good.

    [1]: https://github.com/acacode/swagger-typescript-api

  • utoipa

    Simple, Fast, Code first and Compile time generated OpenAPI documentation for Rust

    play-swagger [2] for scala + play. They generate a significant portion of your spec for you, then a client can be generated from the spec.

    [1] https://github.com/juhaku/utoipa

    [2] https://github.com/iheartradio/play-swagger

  • Play Swagger

    Swagger spec generator for play framework

    play-swagger [2] for scala + play. They generate a significant portion of your spec for you, then a client can be generated from the spec.

    [1] https://github.com/juhaku/utoipa

    [2] https://github.com/iheartradio/play-swagger

  • oatx

    Generator-less JSONSchema types straight from OpenAPI spec

    I’m trying to achieve generator-less mapping from OpenAPI to Typescript types at https://github.com/varanauskas/oatx

  • effect-http

    Declarative HTTP API library for effect-ts

    Something like:

    https://ts-rest.com/

    or https://github.com/sukovanej/effect-http ?

    there are several others in TS world.

  • taxilang

    Taxi is a language for describing APIs, data models, and how everything relates

    One of the gripes I have about OpenAPI is that it has a very low signal-to-noise ratio. It was bad in JSON, it's just as bad in YAML, with an added whitespace pedantry.

    It's great to see a number of alternatives listed in this thread - there's much more active development in this space then I was aware of, and I hope that some of it gets upstreamed back into OpenAPI.

    I'll shamelessly plug our tool in this space - Taxi (https://github.com/taxilang/taxilang), which has a dedicated DSL (not YAML) you can either use standalone, or embeddedd within OpenAPI.

    I also happen to think that (for internal teams at least), generating clients on ${apiSpec} is a form of tight coupling, where producer and consumer become tied together. If you can avoid it, you should, as it allows producers and consumers to stay loosely coupled and evolve independetly without the gymnastics of avoiding breaking changes.

    I've talked about this before, with proposed solutions.[0]

    [0]https://orbitalhq.com/blog/2023-01-16-using-semantic-metadat...

  • GoSwagger

    Swagger 2.0 implementation for go

    Much or some OpenAPI tooling has not even moved past OpenAPI 2.0 some even refusing and saying that they will not update to Swagger 3.0 [0] and others have issues open since some 2019 and still open with no resolution in sight (because these are individuals doing out of passion and the spec is complex to implement) and yet we have Open API spec 4.0

    All this is - trying to do RPC over HTTP in a fashion that was deemed virtuous in some doctoral thesis.

    I wish there were better alternatives for RPC that work everywhere including browsers.

    [0]https://github.com/go-swagger/go-swagger/issues/1122#issueco...

  • swag

    Automatically generate RESTful API documentation with Swagger 2.0 for Go.

  • goa

    🌟 Goa: Elevate Go API development! 🚀 Streamlined design, automatic code generation, and seamless HTTP/gRPC support. ✨

    Few folks in here are (rightly) frustrated with the code generation story and broader tooling support around the OpenAPI standard. I've found a few alternative approaches quite nice to work with:

    - Use a DSL to describe your service and have it spit out the OpenAPI spec as well as server stubs. In other words, I wouldn't bother writing OpenAPI directly - it's an artifact that is generated at build time. As a Go user, I quite like Goa (https://goa.design/) but there are others shared in here like TypeSpec.

    - There are situations where sticking a backend-for-frontend (BFF) in front of APIs can yield great productivity boosts. For example, in the past we built a thin GraphQL proxy that calls out to a poorly structured REST API. Integrating with that was much more convenient. Most recently, I've been playing with a BFF built with tRPC (https://trpc.io/) which calls out to a REST API. It seemed to provide an even better experience if you use TypeScript on the front-end and in the BFF. It does not have a codegen step and I was really pleased with how fast I could iterate with it - granted it was a toy project.

  • http-spec

    Utilities to normalize OpenAPI v2 and v3 objects for the Stoplight ecosystem.

    I'm sorry, but you have completely misunderstood the purpose of Open API.

    It is not a specification to define your business logic classes and objects -- either client or server side. Its goal is to define the interface of an API, and to provide a single source of truth that requests and responses can be validated against. It contains everything you need to know to make requests to an API; code generation is nice to have (and I use it myself, but mainly on the server side, for routing and validation), but not something required or expected from OpenAPI

    For what it's worth, my personal preferred workflow to build an API is as follows:

    1. Build the OpenAPI spec first. A smaller spec could easily be done by hand, but I prefer using a design tool like Stoplight [0]; it has the best Web-based OpenAPI (and JSON Schema) editor I have encountered, and integrates with git nearly flawlessly.

    2. Use an automated tool to generate the API code implementation. Again, a static generation tool such as datamodel-code-generator [1] (which generates Pydantic models) would suffice, but for Python I prefer the dynamic request routing and validation provided by pyapi-server [2].

    3. Finally, I use automated testing tools such as schemathesis [3] to test the implementation against the specification.

    [0] https://stoplight.io/

    [1] https://koxudaxi.github.io/datamodel-code-generator/

    [2] https://pyapi-server.readthedocs.io

    [3] https://schemathesis.readthedocs.io

  • Schemathesis

    Automate your API Testing: catch crashes, validate specs, and save time

    I'm sorry, but you have completely misunderstood the purpose of Open API.

    It is not a specification to define your business logic classes and objects -- either client or server side. Its goal is to define the interface of an API, and to provide a single source of truth that requests and responses can be validated against. It contains everything you need to know to make requests to an API; code generation is nice to have (and I use it myself, but mainly on the server side, for routing and validation), but not something required or expected from OpenAPI

    For what it's worth, my personal preferred workflow to build an API is as follows:

    1. Build the OpenAPI spec first. A smaller spec could easily be done by hand, but I prefer using a design tool like Stoplight [0]; it has the best Web-based OpenAPI (and JSON Schema) editor I have encountered, and integrates with git nearly flawlessly.

    2. Use an automated tool to generate the API code implementation. Again, a static generation tool such as datamodel-code-generator [1] (which generates Pydantic models) would suffice, but for Python I prefer the dynamic request routing and validation provided by pyapi-server [2].

    3. Finally, I use automated testing tools such as schemathesis [3] to test the implementation against the specification.

    [0] https://stoplight.io/

    [1] https://koxudaxi.github.io/datamodel-code-generator/

    [2] https://pyapi-server.readthedocs.io

    [3] https://schemathesis.readthedocs.io

  • datamodel-code-generator

    Pydantic model and dataclasses.dataclass generator for easy conversion of JSON, OpenAPI, JSON Schema, and YAML data sources.

    I'm sorry, but you have completely misunderstood the purpose of Open API.

    It is not a specification to define your business logic classes and objects -- either client or server side. Its goal is to define the interface of an API, and to provide a single source of truth that requests and responses can be validated against. It contains everything you need to know to make requests to an API; code generation is nice to have (and I use it myself, but mainly on the server side, for routing and validation), but not something required or expected from OpenAPI

    For what it's worth, my personal preferred workflow to build an API is as follows:

    1. Build the OpenAPI spec first. A smaller spec could easily be done by hand, but I prefer using a design tool like Stoplight [0]; it has the best Web-based OpenAPI (and JSON Schema) editor I have encountered, and integrates with git nearly flawlessly.

    2. Use an automated tool to generate the API code implementation. Again, a static generation tool such as datamodel-code-generator [1] (which generates Pydantic models) would suffice, but for Python I prefer the dynamic request routing and validation provided by pyapi-server [2].

    3. Finally, I use automated testing tools such as schemathesis [3] to test the implementation against the specification.

    [0] https://stoplight.io/

    [1] https://koxudaxi.github.io/datamodel-code-generator/

    [2] https://pyapi-server.readthedocs.io

    [3] https://schemathesis.readthedocs.io

  • InfluxDB

    Power Real-Time Data Analytics at Scale. Get real-time insights from all types of time series data with InfluxDB. Ingest, query, and analyze billions of data points in real-time with unbounded cardinality.

NOTE: The number of mentions on this list indicates mentions on common posts plus user suggested alternatives. Hence, a higher number means a more popular project.

Suggest a related project

Related posts