[HN Gopher] Analyzing the OpenAPI Tooling Ecosystem
___________________________________________________________________
Analyzing the OpenAPI Tooling Ecosystem
Author : handrews
Score : 50 points
Date : 2024-09-21 19:13 UTC (3 hours ago)
(HTM) web link (modern-json-schema.com)
(TXT) w3m dump (modern-json-schema.com)
| throwaway2016a wrote:
| I find it striking that in the same day I saw a video about how
| someone "Made an API in 20 minutes with one prompt" and this. The
| two approaches seem very divergent. One that is almost cavalier
| about things like security, standards, etc and another that is
| (almost) over engineered.
|
| One observation, is that I there are two trains of thought. Using
| OAD (Open API Descriptions) as a source of truth and generating
| code from there or treating OAD as an artifact that comes out of
| some other tools.
|
| I personally see OpenAPI as kind of a glue that can allow
| different tooling to be able to speak the same language.
|
| Overall I found the linked Moonwalk[1] document to be more
| interesting. But there is some interesting analysis to be found
| in this article as well.
|
| [1] https://www.openapis.org/blog/2023/12/06/openapi-
| moonwalk-20...
| handrews wrote:
| Yeah this article is more about how we (the OpenAPI Initiative)
| are designing the next versions of the OpenAPI Specification
| than it is about how to use it. The diagram does include both
| an OAD generator and editor, intended to encompass both code-
| first and description-first (which doesn't make too much
| difference for this blog post). The Moonwalk article is
| definitely more general purpose! This is "OK Moonwalk has a
| great vision, but how do we actually make it a real spec?" I've
| been using variations of this diagram in the weekly Moonwalk
| calls for the past month or two.
| throwaway2016a wrote:
| > OK Moonwalk has a great vision, but how do we actually make
| it a real spec?
|
| I'm not sure the article really succeeds if that was the
| goal. I suspect that there might be some aspects of the
| discussion that are taking place that are missing from the
| article making it a little difficult for someone who wasn't
| in those discussions to connect the dots.
|
| Don't get me wrong, I think the article had some useful
| pieces in it, I just think if that was the goal of the
| article it could possibly use some additional framing for
| people who don't have the full context.
|
| With that said, I really appreciate transparency into the
| thought process!
| handrews wrote:
| > I just think if that was the goal of the article it could
| possibly use some additional framing for people who don't
| have the full context.
|
| It's always a struggle to figure out how much explanation
| to put in before people see something like "20 minute read"
| and just refuse to read it. (BTW I don't mind the critical
| feedback at all- I'm just glad you found something useful
| in it).
|
| But keep in mind that _we_ haven't answered "how do we
| actually make it a real spec?" either! This is a snapshot
| of our efforts at this particular moment. Also, there's a
| reason that this is "part one in a series" :-)
| dgellow wrote:
| Excellent article, I really like the diagrams
| infocollector wrote:
| Thanks for writing this! This nicely breaks it down into boxes
| that OpenAPI deals with.
|
| I still think OpenAPI usage is a bit confusing in general. For
| example, I am still waiting for a better explanation of this
| diagram with relation to a choice of backend (Python WSGI) +
| frontend (JS) combinations. Perhaps someone here has a pointer
| for me to read?
| dgellow wrote:
| If you haven't yet, I highly recommend to check FastAPI for
| your python backend: https://fastapi.tiangolo.com/. OpenAPI is
| a core part of it, making it simple to integrate with other
| tools such as docs and clients generator
___________________________________________________________________
(page generated 2024-09-21 23:00 UTC)