[HN Gopher] OpenAPI v4 (aka Moonwalk) Proposal
___________________________________________________________________
OpenAPI v4 (aka Moonwalk) Proposal
Author : mooreds
Score : 61 points
Date : 2023-05-31 21:38 UTC (1 hours ago)
(HTM) web link (github.com)
(TXT) w3m dump (github.com)
| hahnbee wrote:
| OpenAPI triggers me so much... It's so painful to use.
| hahnbee wrote:
| of course im glad they are putting in efforts to improve it
| though :)
| gjvc wrote:
| _In this simple example, the moonwalk version has 20% less lines
| and one less level of indentation._
|
| and no different in understandability.
| danappelxx wrote:
| does it add support for streams?
| furyofantares wrote:
| I'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.
| esafak wrote:
| OpenAI's plugins are based on OpenAPI.
| nvrmnd wrote:
| yes, I can confirm this.
| stefankuehnel wrote:
| You are definitely not the only one. It happened to me too. xD
| __jonas wrote:
| you are not to be honest, and I work with Swagger APIs every
| day...
| jeron wrote:
| reminds me of when Snap-On tools had a nice bump in stock price
| prior to Snapchat IPO
| taeric wrote:
| Hard 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.
| klysm wrote:
| I wish OpenAPI had a stronger mapping to typescript types.
| djbusby wrote:
| Or let us describe an custom type (GUID/ULID/UUID)
| adobrawy wrote:
| Do you mean TypeAPI?
| londons_explore wrote:
| pathResponses: 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 wrote:
| Ugh, 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.
| junto wrote:
| It'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.
| contravariant wrote:
| This 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.
| mbell wrote:
| 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).
|
| 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.
| jontro wrote:
| As 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.
| bob1029 wrote:
| I actually got the OpenAPI docgen magic to work 100% all the
| way into Azure API Management Service such that our branded
| portal's docs were being updated based upon code comments each
| time upon merge. It really is something to marvel at. _It
| actually worked_.
|
| That said, I didn't like the amount of moving pieces,
| annotation soup in code, etc. I got rid of all of it. Instead
| of relying on a fancy developer web portal with automagically
| updating docs, I am maintaining demo integration projects in
| repositories our vendors will have access to. I feel like this
| will break a hell of a lot less over time and would be more
| flexible with regard to human factors. Troubleshooting OpenAPI
| tooling is not something I want myself or my team worrying
| about right now.
| taeric wrote:
| Sad 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.
| stickfigure wrote:
| I 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 wrote:
| Why 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.
___________________________________________________________________
(page generated 2023-05-31 23:00 UTC)