8 ms·
OpenAPI v4 (aka Moonwalk) Proposal
- gjvc 3y agoIn this simple example, the moonwalk version has 20% less lines and one less level of indentation. and no different in understandability.
- furyofantares 3y agoI'm certainly not going to be the only one who, confused, read fairly far in before realizing I didn't see the P in OpenAPI.
- Eduard 3y agoThe https://github.com/OAI/ https://github.com/OAI/ Github group name is indeed deceptive.
- samspenc 3y agoI wonder if it was just a matter of them getting that GitHub handle way before OpenAI was a real thing. Update: per Wikipedia, looks like OpenAPI was founded in 2010-11 so that would make sense https://en.wikipedia.org/wiki/OpenAPI_Specification https://en.wikipedia.org/wiki/OpenAPI_Specification
- nvrmnd 3y agoyes, I can confirm this.
- stefankuehnel 3y agoYou are definitely not the only one. It happened to me too. xD
- __jonas 3y agoyou are not to be honest, and I work with Swagger APIs every day…
- jeron 3y agoreminds me of when Snap-On tools had a nice bump in stock price prior to Snapchat IPO
- esafak 3y agoOpenAI's plugins are based on OpenAPI.
- low_tech_punk 3y agoHow about https://github.com/chatgp https://github.com/chatgp
- _ea1k 3y agoI mean, chatgpt does a decent job of working with openapi docs.
- taeric 3y agoHard not to have major WSDL flashbacks in the OpenAPI project I have running right now. Between the lack of support for the latest OpenAPI to generated documentation in Sphinx, custom attributes needed for AWS API Gateway deployment, and the general grossness of adding the OPTIONS requests for CORS access, nothing has worked as easily as I would have thought it would. Especially given so much of the hype. Worse, too many of the client generation libraries all look to be abandoned. With no real indication for me to know which would have a good future.
- jjice 3y agoI consume WSDLs and produce OpenAPI very regularly and you're very right that we've reinvented the wheel. On the bright side, REST APIs are much easier to work with ad hoc and Open API (not sure if this is really because of the format or we just care more now) often has better associated docs.
- nerdponx 3y agoIt's a shame about the tooling. It seems like maybe lack of corporate sponsorship is a problem. I know that many companies use open API internally, but of course are never willing to actually contribute or fund the tools that they depend on.
- taeric 3y agoJust looking at all of the companies in this post that are chiming in to say they are helping the tooling, I think there is no lack of effort. I agree that having a big sponsor would help clarify direction.
- talideon 3y agoThe single dumbest thing we on a team did on a project I used to work on was use the AWS API Gateway. I have my problems with OpenAPI itself, but API Gateway itself is a half-assed mess. If we'd been able to wait a little longer, the lambda serving API requests could've just gotten the HTTP requests directly without that useless heap getting in the way.
- klysm 3y agoI wish OpenAPI had a stronger mapping to typescript types.
- djbusby 3y agoOr let us describe an custom type (GUID/ULID/UUID)
- adobrawy 3y agoDo you mean TypeAPI?
- theogravity 3y agoThis is a problem I also encountered. I created my own OpenAPI generator with hacks around the AST generation to support a field for specifying the TS type of the Request / Response If the spec supports a field to specify the type for a component, that would help a lot with static type generation.
- eyelidlessness 3y agoIt’s definitely possible, with a (fair) bit of glue code. In the past, I wrapped io-ts with OpenAPI docgen logic. This worked great: ~every network boundary type was defined once, providing runtime parse/validation and serialization, inferred static types, and API documentation all at once. Unfortunately I didn’t get permission to open source the solution. But if I ever get bandwidth to build its spiritual successor, I’ll tackle it from the opposite direction: the OpenAPI/JSON Schema specs are very well suited to define the underlying primitives for a zod/io-ts like solution. The great thing about inverting the direction is that it defers “generating” anything to the static type system, ie there’s much less surface area for the runtime and doc schemas to diverge. It also provides opportunities to enrich static types with more information in a general way (eg “brand” a number with its valid range, or a string as a valid email address). This would allow the benefits of runtime checks at API boundaries to be treated as static checks internally without additional/redundant internal runtime overhead.
- klysm 3y agoI’ve been wanting to write a tool that takes in a open api spec and generates zod/io-ts for a while now but I haven’t had the time. That sounds very useful though unfortunate you can’t open it up!
- londons_explore 3y agopathResponses: notFound: status: 404 contentType: application/http-problem apiResponses: serverError: status: 5XX contentType: application/http-problem Can't stuff like this be implicit rather than needing to be defined? Or, to say it another way, we're building this over HTTP, which already defines these things and many others.
- djbusby 3y agoUgh, or try having a mostly common response with just a slight mutation (eg the data is array of Company rather than Contact). Verbose for what could be a "mixing" or "sub-class" or something.
- kelnos 3y agoOpenAPI does support "subclassing" via allOf and oneOf.
- junto 3y agoIt’s explicit in the responses you should expect for a given request, versus what you should expect. For example if the specification defined that a 404 is a valid use case then null or empty list is not considered an exception, but if it isn’t defined in the spec and you receive a 404 unexpectedly, then you can treat it as an exception rather than a valid response.
- cies 3y agoExactly. Also you want to be able to give, for instance, 400s a body that's JSON schema'd
- contravariant 3y agoThis way you can provide a schema for the error such that a client can parse the response. It makes sense for an API schema to include it.
- 3y ago
- mbell 3y agoI'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 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). On the pros side: It does make pretty docs - kinda wish it would just focus on this and in the process not be as strict, I think it would be a better project.
- deleted 3y ago[deleted]
- jontro 3y agoAs for point 1) I fully agree. I'm using it a lot currently due to lack of alternatives, mainly with java. Swagger codegen is the one I've had most success with, but both openapi and swagger codegen shares the same problems. For internal projects we use grpc which is a breeze to use in comparison.
- taeric 3y agoSad to see it isn't just me. I had very real vibes of "surely I'm holding this wrong" in my building an OpenAPI file. And you didn't even mention tools to help deploy, just to help make a client. To add my difficulty, the document generation inside Sphinx was less than up to date. Such that I didn't even get the pretty docs.
- 3y ago
- stickfigure 3y agoI just wish they'd stop using map keys. Use arrays: paths: - name: "speakers" requests: - name: createSpeaker method: post This structure would have allowed adding request name to the schema without breaking everything. This really goes for anyone building REST/JSON APIs. Please avoid dynamic keys; whatever you think the "primary key" is today, it may be different tomorrow. Clients can easily hash an array of objects into a map if they need it.
- echelon 3y agoWhy not accept map keys as nullable similar to what non-required fields in protobuf do? Wouldn't arrays open you up to duplication? More broadly, I'm interested in sparse field updates vs. full payload updates and how each of these handle nullable / emptyable fields. I haven't seen any protocol or standard handle these well.
- withinboredom 3y agoAllow me to introduce you to RFC6902[1]. A standard of how to update without sending the whole thing. There are libraries for almost every language as well. [1]: https://datatracker.ietf.org/doc/html/rfc6902/ https://datatracker.ietf.org/doc/html/rfc6902/
- handrews 3y agoOne of the Moonwalk discussions is indeed about moving from objects to arrays for many structures: https://github.com/OAI/moonwalk/discussions/32 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.
- danappelxx 3y agodoes it add support for streams?
- myvoiceismypass 3y agoSee https://www.asyncapi.com/ https://www.asyncapi.com/ for the equivalent event based spec & tooling.
- hahnbee 3y agoOpenAPI triggers me so much... It's so painful to use.
- hahnbee 3y agoof course im glad they are putting in efforts to improve it though :)
- dandevs 3y agoI feel like this line in the Moonwalk proposal was written for you! "Deep nesting can become unnecessarily cumbersome for reading and writing OpenAPI descriptions."
- kelnos 3y agoMy experience has been the opposite: I've much much much preferred it over the tedium and error-prone-ness of manually writing API clients and server routes.
- cassepipe 3y agoI recently stumbled upon ts-rest which is a contract library, you create a with subcontracts from which you can derive clients which each have their methods, I personally think it's easier and less work that generating clients methods Sorry if that's not very clear, better read : https://ts-rest.com/docs/intro https://ts-rest.com/docs/intro Also, it integrates well with OpenAPI to document the API I am using it between NestJs and SvelteKit and it's great
- iron-s 3y agoHaving full support for the uriTemplates makes reverse mapping impossible, so I suspect adoption of the proposal in the API gateways will be close to 0
- handrews 3y agoThere are ways that URI Templates could be disambiguated for reverse mapping- that would be a discussion worth opening on the Moonwalk repo.
- dandevs 3y agoWhile I have many thoughts about OpenAPI's ease-of-use and readability, I'm going to focus my commentary on the proposal at hand. 1. "The primary goal of this proposal for a major new version of OpenAPI is to make it more approachable in order." -> This is a sound objective. I'm glad to see less nested structures that will improve readability. It'll make it easier to scroll the JSON/YAML and follow the logic. 2. "OpenAPI has become the defacto standard for API descriptions." -> With OpenAI's choice to pick OpenAPI as the standard for ChatGPT plugins, this is more true than ever. It's great to see that now giving names to responses will make it easier for AIs (i.e., ChatGPT, Copilot) to call an API more accurately. 3. No mention of improving the quality of codegen (e.g., client libs, server stubs). Surprised that Moonwalk is silent on this topic.
- handrews 3y agoIf you dig through enough of the discussions, you will definitely see talk around code gen. There's more discussions happening in the background that haven't really percolated out to the moonwalk repo because it's all pretty hand-wavey right now. My intention, when advocating for OpenAPI 3.1 to adopt JSON Schema 2020-12, which brings custom vocabulary support (which I led the design of for JSON Schema), was for additional vocabularies to improve code generation semantics. This has not really happened (for a variety of reasons including that vocabularies weren't quite done and I ended up unable to follow up on the whole thing for several years). It's not entirely clear to me where things go from here, but I suspect Moonwalk will address it in some way. I'd like to focus on it some (from the OpenAPI perspective more than JSON Schema, specifically) but I haven't found anyone who would sponsor that work (I guess the dollars are flowing more to these alternatives several folks have mentioned)
- web3-is-a-scam 3y agoOpenAPI is so crap, it’s the main driving factor for adopting graphql in our organization. Any time we need to go back and add or change existing non-graphql http apis…pulling teeth is preferable.
- AndrewKemendo 3y agoCan you say what is so hard so we can know ahead of time the issues before running into them?
- gibsonf1 3y agoI recommend https://solidproject.org/ https://solidproject.org/ for both data ownership/control and global machine interoperability.
- alpb 3y ago> In this simple example, the moonwalk version has 20% less lines and one less level of indentation. It doesn't sounds like a notable change given a lot of OpenAPI specs are generated and not necessarily read by humans?
- zeroimpl 3y agoAgreed. I'm still using 2.0. I don't write the JSON directly (except for the JSON Schema part), nor do I look at it directly. These major backwards-incompatible changes don't seem like the right move to me, they fragment the tooling and make it difficult for a given library to support multiple versions. This is almost like calling JSON as XML 2.0.
- bterlson 3y agoSince there's a lot of show and tell going on, I'll jump in too I suppose. I work on a tool in this space called TypeSpec (aka.ms/typespec) that aims to address some of the authoring concerns folks have with OpenAPI. We're a language that feels a lot like TypeScript, with support for high-level features you might be used to in a more typical PL, but compiles to high quality OpenAPI 3.0 you can feed into your existing code/docs generation pipeline. You can see this in action on our playground: https://cadlplayground.z22.web.core.windows.net https://cadlplayground.z22.web.core.windows.net. We also support protobuf and (once my PR gets merged) JSON Schema targets. We're not yet to beta (obviously, no website even) but we're hoping to get there relatively soon. Happy to hear any thoughts, especially from folks using OpenAPI.
- dcre 3y agoThis is great. After a couple of years fighting OpenAPI in various ways, I can definitely see the case for giving the spec its own proper language that’s not JSON. Seems inspired by GraphQL’s really nice specs (IMO the only nice thing about GraphQL).
- bterlson 3y agoThank you! We take most of our inspiration from TypeScript and sometimes C#, but I agree that gql demonstrates the value of terse, highly readable specs quite nicely.
- dcre 3y agoI looked through the docs and now I have a question! It seems like part of the advantage here is being able to represent things in the spec that OpenAPI might have a hard time with. For example, a ResultsPage<T> template represents structure that's shared across a bunch of paginated endpoints regardless of the type of the items. In OpenAPI, each of those responses has to get its own type (ResultsPageA, ResultsPageB, etc.), and presumably in the generated OpenAPI spec, the fact of that shared structure must be lost, and therefore cannot be picked up by client generators that work on the OpenAPI spec. How do you think about the relation to OpenAPI v3 (i.e., setting aside possible improvements in v4) — is the goal of TypeSpec to avoid doing things that are too far afield from what you can represent in OpenAPI, or is the OpenAPI thing more like a bridge to adoption so people can use their existing generators, but in the future you imagine people generating clients from TypeSpec directly?
- ohnoesjmr 3y agoMaybe its just me, but I'd always pick gRPC, a lot less headaches than the community (un)maintained codegen for some random language.
- addcn 3y agoI don’t think a new spec is going to make it easier for more teams to use OpenAPI. This isn’t the problem… What we really need is better tooling to help developers maintain the spec and built generators on top of it. I’ve been building open source API version control tools built on top of OpenAPI. It’s an easy way to keep your spec up-to-date just by looking at test traffic. If it detects a diff, it will update the OpenAPI sort of like a snapshot test. https://www.useoptic.com/cli https://www.useoptic.com/cli
- lolinder 3y agoThe big weak point I've always seen in OpenAPI is that every change in the server needs to be mirrored in the spec. This opens up a lot of surface area for mistakes. What I really want is a way to generate clients from the server source. I realize that this would require a highly opinionated web server with strong typing on all endpoints, but that just sounds like extra value to me. Are there any web frameworks that enable generating clients like this, whether through a generated OpenAPI spec or otherwise?
- deleted 3y ago[deleted]
- arcanemachiner 3y agoDjango Rest Framework + drf-spectacular. It needs a couple tweaks here and there but it's great. Apparently django-ninja (a different REST framework for Django) also generates an OpenAPI spec but I haven't tried it.
- cachance 3y agoI've also had success with drf + drf-spectacular and then using the output OpenAPI spec to generate a typescript-react client with a third-party code generator. It mostly just works, like you said, and almost acts as a framework guardrail: if the inferred client types are comprehensive and unsurprising then the view tends to be concise; a wonky type indicates there may be something nonstandard in the view that could be fixed by cleaner framework-abiding code.
- danappelxx 3y agoI suspect OpenAPI advocates would argue you should start with the spec and use it to generate both the client and server. This is already a common pattern in other RPC definition languages such as gRPC. You _could_ write a server to match the gRPC spec, but why would you?
- lolinder 3y agoThat works great if you're starting from scratch, but not so much if you're on a brownfield project. The way the generators are written, even generating a new endpoint can't be done after code has been written because it generates a whole file with route stubs.
- deleted 3y ago[deleted]
- denkmoon 3y agoEvery time I try to use an OpenAPI document to generate client code, it fails, I talk to the customer and they say "oh no don't do that, it's not meant for generating code from". Not an indictment on OpenAPI but it's truly bizarre how people use it.
- clintonb 3y agoI’m working with a spec that used GUIDs for their operation IDs. This limits TypeScript code generation to typescript-node, which prepends an underscore on the method names. Otherwise, those starting with numbers would be invalid.
- withinboredom 3y agoThis annoys me so much. Like, just use array-style accesses in the code generator?
- clintonb 3y agoYes, but also generate a spec with meaningful operationIds. “getLabels” is much more useful that “529ab782”.
- withinboredom 3y agoI was mostly thinking about 'in' and other kinds of language keywords that get prepended with underscores and stuff.
- seer 3y ago> A side effect of giving names to requests and responses is that it makes the predictions from AIs like GitHub Copilot significantly more effective. Hmm first time I see an api try to cator to AI tools rather than the other way around, feels like we’ve turned a corner for AI tools. Wonder what will happen when we start to design code / libraries / languages with this in mind. I have a feeling there will be a “designed for ai” language that is going to sweep our industry, maybe turn the languages of today in the same place as assembly/forth - nice for some specific applications, but not mainstream…
- sroussey 3y agoI’ve thought of this as well. Maybe even inline assembly which might actually be something like JS/python/rust. It might look like inline SQL does now.
- pmkelly4444 3y agoCould you give an example of how this would work with an API? Trying to understand what you mean
- sroussey 3y agoWhat API? This would be a new programming language!
- wiremock 3y agoWe follow the Moonwalk project in WireMock, because the new features clearly provide some opportunities for better API integration testing and request/response validation that us now embedded in WireMock 3 Beta. Our TL;DR: the standard looks interesting, the developer tools need a lot of love. The whole world is using JSON/YAML these days, but developer experience for JSON Schema is lightyears behind "legacy" XSD
- handrews 3y agoI'll repeat a relevant bit from an earlier reply of mine: The ideal system, to me (speaking as the most prolific contributor to JSON Schema drafts-07 through 2020-12), would have clearly defined code generation and runtime validation features that did not get in each other's way. Keywords like "anyOf" and "not" are very useful for runtime validation but should be excluded from type definition / code generation semantics. This would also help balance the needs of strongly typed languages vs dynamically typed languages. The fundamental problem is that JSON Schema was designed as a constraint validation system (https://modern-json-schema.com/json-schema-is-a-constraint-system https://modern-json-schema.com/json-schema-is-a-constraint-s...) and it's been overloaded for type definition in ways that don't always make sense. But the JSON Schema alternatives that I've seen go too far in the other direction. There is a lot of value in being able to perform more complex runtime validation in a language-independent way. There is a balance and clear separation of concerns needed between data definition and runtime validation, although they still should live in the same contract as there is considerable overlap. Now if I could only find someone who wants to fund the design of such a system... :-)
- RamblingCTO 3y agoI was always a big proponent of openAPI. But the reality is: the client generators are often times lacking, spewing out shitty code with ages old dependencies. You sometimes have to make weird mental acrobatics to get your API reality modelled. Then, not directly related, you have the problem of each service having to have their own client. Maintenance doubles. We're going down the graphQL federation with "one graph" for backend services path now. Surely not a holy grail but way better than openAPI.
- koreth1 3y agoThe projects I work on generate OpenAPI docs at runtime based on annotations in the server source code, so they're always guaranteed to be in sync with the actual API. We've had to add some custom logic to clean things up a bit (e.g., in places where we have custom JSON serialization logic) but luckily the library we're using has hooks for that purpose and it hasn't been a huge pain point. But like others have said, the client code generators leave a lot to be desired. For example, I have yet to find one that properly deals with recursive data structures like an arbitrarily-nested tree structure with multiple node types. Several of them just flat-out crash, and the ones that don't generate code that won't compile or that bombs out. We've had to resort to hacks like tagging the recursive structures' descriptions with magic keywords that trigger a postprocessing step to fix up the generated code. But I don't really view this as a problem with OpenAPI per se. The data structures in question can be correctly and unambiguously described in the OpenAPI JSON document.
- martypitt 3y agoOne 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 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-metadata https://orbitalhq.com/blog/2023-01-16-using-semantic-metadat...
- liampulles 3y agoI've found OpenAPI to be fine to work with until you start trying to do really silly things with query parameters or multipart bodies, etc. I can understand why OpenAPI has those issues though - it is because OpenAPI is aiming to DOCUMENT APIs rather than SPECIFY them. That is a hard task given how wide a set of things you can do with HTTP. So be charitable when comparing OpenAPI to XYZ API specification tool.
- aranw 3y agoMy biggest pain point is the fact that OpenAPI uses YAML. They always demo it with the simple short examples but soon as you go above a handful of endpoints the YAML will be just horrible to maintain. This is not my only pain point with OpenAPI but it's definitely my biggest. I'd rather use something else and then generate out OpenAPI specs
- mdaniel 3y agoI evidently need to put this reply in a hotkey or something, because it comes up every time someone rants about yaml, but if you hate yaml so much then write it in json as yaml is a superset of json
- handrews 3y agoYou can write it in JSON, you know. Not even "JSON as a subset of YAML" but actual JSON. The proposed media types are application/openapi+yaml and application/openapi+json
- wg0 3y agoMuch 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. EDIT: typos [0]https://github.com/go-swagger/go-swagger/issues/1122#issuecomment-575968499 https://github.com/go-swagger/go-swagger/issues/1122#issueco... [1]https://github.com/swaggo/swag/issues/386 https://github.com/swaggo/swag/issues/386
- incrudible 3y agoThe doctoral thesis does not describe RPC at all. It is a more general description of a request/response pattern for navigation of something like a website, by an agent. I would wager that virtually nobody read the thing, and some of those that actually did drew bad conclusions, e.g. pushing for HATEOAS in their API.
- nerdponx 3y agoWell I am more optimistic about its usefulness than you, I agree that it's a little ridiculous to announce v4, when v3 was out for over a year before it had decent support from tools like Postman and Swagger UI. There seems to be a disconnect between the people creating the standard and the people implementing it.
- handrews 3y agoOAS 3.0 is pretty well-supported by now. One of the biggest lags was Swagger, and they now support 3.0 and are finally making progress on 3.1. One factor in 3.1 support is that it came out more-or-less concurrently with JSON Schema draft 2020-12, and depends on it. 2020-12 support has recently become more common across more languages, and we're seeing 3.1 work pick up the pace a bit. But (from years of experience working on these standards), there is _always_ a lag in adoption. You can't just sit and wait until everyone "catches up" because that won't really shorten the lag to the next major version (OAS 3.1, despite the numbering, had significant enough changes to lag like a major version). So while I'd agree that it's slower than if there were a clear and well-funded owner of things (which is closer to the situation with AsyncAPI), it's not _unusually_ slow as these things go.
- bcoughlan 3y agoContrary to some others experience here I've had good results writing OpenAPI YAML and generating server stubs in Spring. Because it's generating strongly typed code we get a lot of guarantees that the docs match the implementation. For working with frontend devs it's a huge win over the lossy communication of word-of-mouth API docs. It is definitely verbose to write and Moonwalk would help. Co-pilot helps a huge amount, but I do crave a DSL that's not indentation based.
- deleted 3y ago[deleted]
- disintegrator 3y agoFew 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/ 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/ 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.
- cheradenine_uk 3y agoDoing an API-first approach - which I recommend - a) involves an incredible amount of DRY in the specs (to the extend we tinkered with a DSL to generate the openapi which feels wrong) b) doesn't have very good ways of splitting large files up and c) is YAML which is horrible. (Yes, JSON too, but that's even worse for authoring). I can see if you're trying to describe an existing API with OpenAPI there are enhancements here which you will welcome. If you're using OpenAPI to develop new APIs, I've come to the conclusion of "don't. Use GraphQL". After initially worrying about over-fetching and N+1 stuff, and thinking "yeah GraphQL for the front end, but the serious stuff should be OpenAPI" I've ditched that. GQL Federation was the final nail; it /does/ force some conversations up the chain (how exactly ought two, supposedly completely independent APIs, federate) but in practice this is a useful attribute.
- StackOverlord 3y agoI have a question: how do these systems handle webhooks ? Do they generate event handlers too ? I'm asking this because notions like "quality of service" are essential when you're dealing with the semantically asynchronous parts of an API. With MQTT you can chose between QOS 0 (at most one, this is fire and forget HTTP events, very bad), QOS1 (at least once) and QOS2 (exactly once). This imply coding some kind of broker that will track the state of the communication and carry it to its completion.
- Meic 3y agoOpenAPI Technical Steering Committee (TSC) member and OAS Community Manager here. Happy to answer or redirect all questions related to Moonwalk / OpenAPI v4.