Our great sponsors
-
connexion
Connexion is a modern Python web framework that makes spec-first and api-first development easy.
-
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.
-
openapi-code-generator
A code generation tool for openapi 3 / 3.1 specifications written in typescript, primarily aimed at generating typescript clients and server stubs. Other target languages may be added in future.
-
-
-
laminar
OpenApi backed REST APIs. Automatic validation of request / response based on the api schema. (by ivank)
TypeSpec and Smithy live in a similar space here. You can generate OpenAPI specs from them, or you can generate assets directly from them. OpenAPI is one of the many possible outputs from TypeSpec.
This is an example the author created of TypeSpec being used to generate clients in many languages as well as the OpenAPI spec.
https://github.com/bterlson/typespec-todo
I like the idea, especially the TS-like syntax around enums and union types. I've always preferred the SDL for GraphQL vs writing OpenAPI for similar reasons.
I echo the sentiment others have brought up, which is the trade-offs of a code-driven schema vs schema-driven code.
At work we use Pydantic and FastAPI to generate the OpenAPI contract, but there's some cruft and care needed around exposing those underlying Pydantic models through the API documentation. It's been easy to create schemas that have compatibility problems when run through other code generators. I know there are projects such as connexction[1] which attempt to inverse this, but I don't have much experience with it. In the GraphQL space it seems that code-first approaches are becoming more favored, though there's a different level of complexity needed to create a "typesafe" GraphQL server (eg. model mismatches between root query resolvers and field resolvers).
[1] https://github.com/spec-first/connexion
Yeah I'm also on the schema first side of the debate.
I think for me it comes down to a few key points:
- APIs are forever, the choice of language/framework is an implementation detail
- Constraining yourself to what can be represented in the specification is better than generating a specification from implementation that may not be capable of expressing the full details
- When working with diverse languages it provides a common ground/language for discussing API changes. Eg: if you have java backend, kotlin android, swift iOS, react/whatever web you can bring everyone together with the spec
- Subjective, but a good spec will include a bunch of documentation and examples that tend to create a lot of noise in the code. I personally prefer to keep this in the spec and the implementation smaller
I think the main counterpoint to this is that you can generate the spec and then take that and change your mind if you later change language/framework etc - it's not a one-way door.
My biggest bug bear is that regardless of spec first or implementation first, you should have something you write once and generate the rest of the glue from (eg: docs, client sdks). Writing each piece manually/independently always leads to drift and bugs.
(I'm working on my own little openapi -> typescript code generator over here https://github.com/mnahkies/openapi-code-generator - eventually plan to support more than typescript, and adding typespec support is something I'm currently considering)
TypeSpec is great, but if you're working with Rust and you're about to write a new project that will require an OpenApi spec sooner or later, I'd like to recommend a web framework that has spec generation baked in:
https://github.com/poem-web/poem (see poem_openapi)
All you need to do is derive a trait on your response structs and in return you get an almost perfectly generated spec. Unions, objects, enums are first class citizens.
Also, if you're from coming from PHP, the controllers feel very much like symfony controllers.
P.s. Please do recommend an ORM that would feel closer to doctrine. I miss doctrine.
It does not exist, but it will be worked on fairly soon. You can track progress on GitHub [1]. It will be as you suggest - a one time conversion, after which you can iterate. We have this workflow for inside Azure, but the converter is Azure-specific (e.g. converts to TypeSpec that uses our extensive Azure-specific component library). It will take a bit to generalize.
[1]: https://github.com/microsoft/typespec/issues/3038
Yeah also schema-first here. I think this is the “easy vs simple” debate all over again.
Writing code first schema is very easy, but when you start _using_ that api as part of a greater system is where the approach starts falling short.
Schema first allows for great communication between teams - one team requires changes to an api service, they can hash it out with the api, and then go back and implement both the client _and_ server simultaneously.
The great benefit here is the inevitable back-and forth can be done together, as each side might need to adjust the api while they are implementing the client/server as often happens with engineering efforts. And thats a lot easier to do while each side is working on it rather than the usual one side is “done” and moves to another task and needs to go back and modify.
In fact at the time I built quite a nice system of generating typescript types for both client and server - https://github.com/ivank/laminar
I guess because the project tried to introduce strong typing and fp style to node http servers plus a few other ideas stolen from here and there, it tried to do too much and never really got traction.