connexion

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. Most APIs I've run into in my career would benefit from modeling their API responses as ADTs versus the usual approach of overloading 4 different union members into a giant spare object. 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 h

What's the use case? I was thinking about this exact issue because my product ships several CLI tools, but I wasn't convinced it would be worth the effort. An OpenAPI specification describes an HTTP interface, and I see it as useful because it makes it easier to write code in language-of-choice to generate HTTP requests (by generating client libraries from the OpenAPI spec). For a CLI, the interface is the command-line. Usually people type these commands, or they end up in bash scripts, or sometimes they get called from programming language of choice by shelling out to the CLI. So I could see a use case for a CLI spec, which would make it easier to generate client libraries (which would shell out to the CLI)... but it seems a little niche. Or maybe, as input to a documentation tool (like Swagger docs). I would imagine if you're using a CL

Hey just to let you know -- the reason I'd pick something like FastAPI over pyotr is because I don't want to write the OpenAPI -- I personally see code on the backend as the source of truth, and prefer for it to go the other way (Swagger/OpenAPI YAML/JSON generated from code). Other than that, library looks cool! like connexion[0] but starlette based. Might be worth putting a comparison on your page? [0]: https://github.com/zalando/connexion

I work at a rather large company that has an internal gateway for all APIs. Each api has an associated OpenAPI doc and the standardization makes it incredibly easy to peruse all capabilities across the company, despite programming language, organizational, and physical barriers between developers. I concede that the magic there is in the standardization of API level docs, and not the special sauce that OpenAPI brings to the table. I just don't know of an alternative that is as language agnostic as OpenAPI. Personally, I enjoy using server frameworks with first class support for OpenAPI. The projects I've used it in have forced me to write documentation first, and really think about what I'm trying to accomplish from a design perspective. I am by all metrics a very average developer, and a tool that pushes me to think in a new way is one I

We use Connexion at work, which supports v3 now (though we haven't gotten around to updating it from 2 yet). If you use python/flask, I _highly_ recommend checking out Connexion: https://github.com/zalando/connexion

https://github.com/zalando/connexion/ Solves most of the problems for that.

I have used Connexion (https://github.com/zalando/connexion) in the past. The only thing I didn't really like is that the OpenAPI file grows rather unmaintainable after some time if you have a big service.

If your interested in flask and api's have a look at https://github.com/zalando/connexion, but personally I'm more a bottle kind of guy.

Swagger Editor[1] can spit out the skeleton of a Flask based server from an OpenAPI 2.0 specification. The generated code makes use of the Connexion famework[2]. Paste your specification into the editor, fix it if it's not valid, open the "Generate Server" dropdown in the top menu, and select "python-flask". [1] http://editor.swagger.io/ [2] https://github.com/zalando/connexion/

While Swagger might not be perfect (some pain points are addressed with OpenAPI v3) it works IMHO pretty well for us (Zalando) and myself doing API first: * use a decent editor to write the YAML e.g. https://github.com/zalando/intellij-swagger * do not write any boilerplate code and do not generate code (if that's possible in your env), e.g. by using https://github.com/zalando/connexion (Python API-first) * follow best practices and guidelines to have a consistent API experience, e.g. https://zalando.github.io/restful-api-guidelines/ Most importantly Swagger/OpenAPI gives us a "simple" (everything is relative!) language to define APIs and discuss/review them independent of languages as teams use different ones across Zalando Tech.

I often write swagger files that are fed to a library[0] that maps them to Flask endpoints and does input validation. Writing the schema is always a painful experience. I find the result overly verbose and not human friendly. Which makes me think that these things shouldn't be hand crafted. > I believe this can be very interesting since it allows you to centralize documentation, generate protocol-agnostic clients to share with other teams in your organisation, etc. On the paper yes, but I have yet to come across formal API specification used this way. The only usage I see in the wild is the generation of web API browsers, a la swagger UI. [0] https://github.com/zalando/connexion