Hey you might want to note a bit more about what exactly this does and how it does it on the README. I went to the page and was thoroughly confused -- does this library:
- Read application code (written in python?) and extract an API specification? Is it flask only?
- Does it update the file on disk repeatedly?
- Does it modify generated application code to add an endpoint for the Swagger UI and host it?
- Are any modifications to the pre-existing applications necessary?
- Does it wrap an existing application?
Good tools also often have a comparison section -- are there other tools in your space that do what you do, but differently?
I'd like to think I'm familiar with the Swagger/Swagger2/OpenAPI3 space, and I'm aware of tools that go spec->code (usually generating clients/servers) and code->spec (whether by comments, annotations, or some other language mechanism), but it's not clear what your tool actually does.
Hello. Yes, I have not prepared enough the description so guys and ladies I am sorry for that. Just added more information to the README.md file on GitHub.
Answers to the questions:
> - Read application code (written in python?) and extract an API specification? Is it flask only?
You can:
1. Construct schema objects and request objects using Python classes with marshmallow [1] library;
2. Split API paths (routes) into separate python modules, files for convenience and then add them in the `api/project.py` file.
> - Does it update the file on disk repeatedly?
No. You need to re-build the `api.yaml` file by yourself, using this command: "python build.py"
> - Does it modify generated application code to add an endpoint for the Swagger UI and host it?
No. You need to write the business logic of your API by yourself. For example, you write an API in Go and describe the API definitions (specifications) using
my project just by adding new paths, schemas. Flask is used only for development purposes, it is not meant to create API using Flask, but you can do it as well.
> - Are any modifications to the pre-existing applications necessary?
No.
> - Does it wrap an existing application?
If you meant if this is a wrapper for other apps then it is. These two: marshmallow [1] and apispec [2]
If you meant if this wraps existed API then the answer is yes. You can describe existing APIs using my project.
> ... are there other tools in your space that do what you do, but differently?
Yes, a lot and for many languages. I can mention swagger-php [3], flask-swagger [4] which I know. But the two are using annotations in code (via docstrings) to describe the API definitions/specification when my project is meant to create ONLY API defs/spec.
As I said before the project isn't related to business logic of your APIs but I can show you an example how you could use it. It's an example about how to create an API in Go.
After generating an api.yaml file go to api-spec-converter [1] and convert content of API spec in OpenAPI 3 format to Swagger 2.
Then download an executable file of go-swagger [2] and run this command to generate all boilerplate code for your server:
swagger generate server -f ./swagger.json -A pet-api
This way you can firstly prototype (describe all paths, schemes, and requests) of your API and only then to start to write code. It's hugely simplifying the process of coding in my opinion.
Shameless plug, I did something similar in Rust (that is, 2017 rust that I haven't gone back to) for my MEng project.
I really wish more APIs/people used OpenAPI, I think/thought it's fantastic, but I haven't really used it since. Docs-only at work, a bit, but it has so much more potential.
--
Main difference in mine is that I used the OpenAPI spec as the starting point though - I wanted to be able to use it as an API-specific HTTP client. From that I inferred type signatures at compile-time in order to enforce correct (per the spec) use of an API, and enforce handling all the (stated) possible error cases. Idea being that if you did the same on the server side, you'd have pretty good guarantees about your communication.
Kept meaning (still mean?) to go back to it, but I haven't yet. It supports the basics, but it's far from battle-tested; I might never get back to working on it, but if it's of interest to anyone for (absolutely non-production) toying around, I'll certainly respond and act on any PRs.
It seems they're not linked from the readme (probably I was scared to update it post-deadline in case of examiner doubt, and presentation/slide manufacture was post-submission deadline) but there's also slides (linked from the release) that perhaps have a bit more detail on what I was going for from a more technical perspective (though it's been a while):
This was a fantastic introduction to modern performant/typesafe python -- I had no idea FastAPI existed, and did not know about the projects it depends on, starlette[0] and pydantic[1].
Prior to today if I was starting a python project I probably would reach for PyPy + falcon/flask/django and go until I hit a limitation that required CPython, but with starlette/pydantic I'm more than happy to settle for NodeJS-like performance on CPython. And of course, the OpenAPI/Swagger support is an amazing feature, APIs shouldn't be built without it these days.
As someone who used openAPI for the first time recently, I don’t understand the benefit.
Im building an integration between two different API’s. I was given the openAPI spec and instructed to find a mock server generator to get a boilerplate app up. I spent like two hours trying to find some sort of generator that provides value. All the generators I tried seemed half baked (I wanted to use rails for this project, because that’s what I am most familiar developing in. I understand rails is a sub optimal choice for this project.)
In the time I wasted trying to find a generator, I could’ve just wrote the code by hand. Once I just started manually writing code, everything started moving much quicker. Even if I had used a generator, I’d still need to manually update things every time the interface changes, yeah? Who is openAPI for?
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'd like to use.
That said, different strokes for different folks. I am sure it is a massive headache to deal with all that YAML if you're not getting anything out of it.
How do you deal with reasonably complex data structures in OpenAPI?
We're in desperate need of an API documentation solution, and i reached for OpenAPI early on but found it (the UIs availab,e specifically) immensely confusing. It looks great when it's a small flat object, but when you're returning hundreds of unique fields and structures, lots of enums, etc - the result is an automated mess.
I don't think this is strictly a fault of the spec, but of the UI. They seem to design it around the pet shop example, which doesn't seem beneficial to any of our internal, large API responses.
I've also written a small custom JS script that generated an OpenAPI spec file by reflecting over some internal data structures, so that's an option as well, and there's lots of tools out there for generating OpenAPI specs based on code (Java annotations, Python models, etc).
You're right that tools are almost all partially-baked.
I use specs to generate data models in TypeScript, Kotlin, and .NET (for different projects). This gives me compile-time guarantees that my API docs match my code.
I also use it for generating documentation and client SDKs in other languages.
If used correctly, it can help automate hundreds or thousands of hours of error-prone work. It also forms an unbreakable contract between systems in totally different languages (not unlike what Protobufs could be used for).
It takes a few hours to find tools you like, but after that, it's generally smooth.
What's your preferred tool for generating TS API clients? I tried the official `openapi-generator` tool last year, but was horrified to see that a fairly small API file resulted in 5000 lines of boilerplate TS code that was trying to provide multiple levels of overrides and abstraction for configuring the calls.
I don't actually generate clients. I generate data types for requests and responses, which I then use with regular HTTP clients.
I'm sure there are some client generators out there that work well and create lean code, but it's easy enough to use off-the-shelf HTTP clients with some additional type guards.
I spend weeks looking for tools that I could even us, much less like, and eventually gave up and wrote everything by hand. I would be very interested in hearing about any OpenAPI tools that you would recommend.
For .NET, it's best to write the spec as annotations on your controllers and request/response classes using NSwag[1].
The situation is similar in the Java world. It's better to annotate, rather than start with your own spec.
For TypeScript, I mostly use a CLI tool[2] that generates type definitions, which I then use in my routing system and controllers to make sure that any changes to paths, requests, and responses are going to cause compiler errors until they're fixed.
The best CLI documentation generator I've found so far is Redoc[1].
There are tons of hosted solutions for docs (Apimatic, SwaggerHub, Stoplight, and Apicurio Studio).
My favorites are SwaggerHub[2] and Apicurio[3], because their editors are solid and they have good compatibility with all the nooks and crannies of the OpenAPI v3 spec.
Hey, I use it at work. It's really just a fairly stable way of documenting APIs. Sure you can try do fancy generation of it from one side, and generate code on the other, but treat it just as a standard way of talking about requests and responses and you'll see the benefits.
If you do want a good benefit, here's a testing engine that'll run through an OpenAPI file and confirm the server's adhering to it correctly: https://dredd.org/en/latest/
My two cents, Using OpenAPI enables in going API first. The stakeholders agreeing on an API is perhaps one of the most important things in lifecycle of the product and rest of the things really just snowballs from there. Also, an API that changes frequently is perhaps not a good sign, it will hurt the clients, new version of the API is different thing though.
Shameless plug: I have been developing Pyotr [0], a helpful async library - based on top of Starlette [1] and httpx [2] - which is using OpenAPI as the specification for routing and validation, both on server and client side.
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?
> I personally see code on the backend as the source of truth
That is a perfectly valid approach, although when you need to coordinate development between multiple teams starting with a specification can be really helpful. That doesn't mean that the spec has to be written once and frozen, as long as everyone is aware of the changes and adapts accordingly.
> Might be worth putting a comparison on your page?
I have indeed started the development when I found that connexion does not completely meet my requirements. The main difference is that pyotr supports ASGI, so can work with any ASGI framework (I haven't tried it with Mangum yet, but am planning to). Additionally, pyotr has a client component, which was inspired by Bravado.
> That is a perfectly valid approach, although when you need to coordinate development between multiple teams starting with a specification can be really helpful. That doesn't mean that the spec has to be written once and frozen, as long as everyone is aware of the changes and adapts accordingly.
True! I wonder if there's a good way to actually keep teams abreast. I actually end up writing specs by hand from time to time when I just want to get started quickly, but it can be such a pain.
Oh but one of the cool things I was able to set up is automatic generation of client libs (and pushing to a git repo) with GitLab -- it's really awesome to be able to automatically generate client libs that match your API versions.
> I have indeed started the development when I found that connexion does not completely meet my requirements. The main difference is that pyotr supports ASGI, so can work with any ASGI framework (I haven't tried it with Mangum yet, but am planning to). Additionally, pyotr has a client component, which was inspired by Bravado.
So I didn't actually know what ASGI was until I read your existing documentation! I'm not a huge python person but I'd heard of WSGI and some of the other variants but hadn't heard of ASGI! Thanks for the background on the client as well
I've been out-of-the-loop for a while, what's the state of the art in re: OpenAPI/Swagger?
What I mean is, are people using it in the wild? Are there mature (or at least pretty stable) code generators? Test generators? What's inter-operability like? (Is it easy/possible to generate clients and server stubs in different languages that will work together? Can I write a service, publish my API spec, and expect people to be able to use it to write clients?)
As other mentioned this the description is particularly non-user friendly for something that (as far as I understood) is related to a documentation management system.
I'm mostly a backend GUI but still interested in learning more about web API. But the only description sentence is presuming that reader is comfortable with a highly specialized jargon. On the other hand I smell that "any project" is probably far narrower than it sound.
> The goal of this project is to create a generator that conveniently creates API definitions in OpenAPI 3 format and then injects the generated YAML file with Swagger UI to any project.
I am confused when people try to generate api specs from languages (e.g. typescript to openAPI). The big draw to API specs for me is language independence. By generating from an implementation it's the wrong way round and you lose a degree of freedom IMHO.
I agree with this position. The code and the API spec must be separated. But the project is not meant to write APIs with spec, the project uses Python to create API spec.
the README file of this repo does not help me understand what this project is about as someone who has never used OpenAPI (and only faintly used Swagger UI for a short time before).
- Read application code (written in python?) and extract an API specification? Is it flask only?
- Does it update the file on disk repeatedly?
- Does it modify generated application code to add an endpoint for the Swagger UI and host it?
- Are any modifications to the pre-existing applications necessary?
- Does it wrap an existing application?
Good tools also often have a comparison section -- are there other tools in your space that do what you do, but differently?
I'd like to think I'm familiar with the Swagger/Swagger2/OpenAPI3 space, and I'm aware of tools that go spec->code (usually generating clients/servers) and code->spec (whether by comments, annotations, or some other language mechanism), but it's not clear what your tool actually does.
Answers to the questions:
> - Read application code (written in python?) and extract an API specification? Is it flask only?
You can:
1. Construct schema objects and request objects using Python classes with marshmallow [1] library;
2. Split API paths (routes) into separate python modules, files for convenience and then add them in the `api/project.py` file.
> - Does it update the file on disk repeatedly?
No. You need to re-build the `api.yaml` file by yourself, using this command: "python build.py"
> - Does it modify generated application code to add an endpoint for the Swagger UI and host it?
No. You need to write the business logic of your API by yourself. For example, you write an API in Go and describe the API definitions (specifications) using my project just by adding new paths, schemas. Flask is used only for development purposes, it is not meant to create API using Flask, but you can do it as well.
> - Are any modifications to the pre-existing applications necessary?
No.
> - Does it wrap an existing application?
If you meant if this is a wrapper for other apps then it is. These two: marshmallow [1] and apispec [2]
If you meant if this wraps existed API then the answer is yes. You can describe existing APIs using my project.
> ... are there other tools in your space that do what you do, but differently?
Yes, a lot and for many languages. I can mention swagger-php [3], flask-swagger [4] which I know. But the two are using annotations in code (via docstrings) to describe the API definitions/specification when my project is meant to create ONLY API defs/spec.
[1]: https://marshmallow.readthedocs.io/en/stable/
[2]: https://github.com/marshmallow-code/apispec
[3]: https://github.com/zircote/swagger-php
[4]: https://pypi.org/project/flask-swagger/
You know what would make it really clear -- a "Quick Start" section, show me how to go from 0 to 1 with your library.
From what I can gather:
- `pip install` your library
- create a golang project
- write some routes (and annotate them accordingly)
- call your library via `python ...` (?)
- api.yaml is written to my directory
Thanks for open sourcing this software!
Yesterday I extended the README file so you can start using information from this section: https://github.com/egorsmkv/openapi3-generator#how-to-use
As I said before the project isn't related to business logic of your APIs but I can show you an example how you could use it. It's an example about how to create an API in Go.
After generating an api.yaml file go to api-spec-converter [1] and convert content of API spec in OpenAPI 3 format to Swagger 2.
Then download an executable file of go-swagger [2] and run this command to generate all boilerplate code for your server:
swagger generate server -f ./swagger.json -A pet-api
This way you can firstly prototype (describe all paths, schemes, and requests) of your API and only then to start to write code. It's hugely simplifying the process of coding in my opinion.
[1]: https://lucybot-inc.github.io/api-spec-converter/
[2]: https://github.com/go-swagger/go-swagger
I really wish more APIs/people used OpenAPI, I think/thought it's fantastic, but I haven't really used it since. Docs-only at work, a bit, but it has so much more potential.
--
Main difference in mine is that I used the OpenAPI spec as the starting point though - I wanted to be able to use it as an API-specific HTTP client. From that I inferred type signatures at compile-time in order to enforce correct (per the spec) use of an API, and enforce handling all the (stated) possible error cases. Idea being that if you did the same on the server side, you'd have pretty good guarantees about your communication.
Kept meaning (still mean?) to go back to it, but I haven't yet. It supports the basics, but it's far from battle-tested; I might never get back to working on it, but if it's of interest to anyone for (absolutely non-production) toying around, I'll certainly respond and act on any PRs.
https://github.com/OJFord/tapioca
It seems they're not linked from the readme (probably I was scared to update it post-deadline in case of examiner doubt, and presentation/slide manufacture was post-submission deadline) but there's also slides (linked from the release) that perhaps have a bit more detail on what I was going for from a more technical perspective (though it's been a while):
https://github.com/OJFord/tapioca/releases/download/v0.0.1/s...
https://fastapi.tiangolo.com/
Auto generates both interactive SwaggerUI and Redoc pages.
Can turn off before production deployment.
Prior to today if I was starting a python project I probably would reach for PyPy + falcon/flask/django and go until I hit a limitation that required CPython, but with starlette/pydantic I'm more than happy to settle for NodeJS-like performance on CPython. And of course, the OpenAPI/Swagger support is an amazing feature, APIs shouldn't be built without it these days.
[0]: https://starlette.io/
[1]: https://pydantic-docs.helpmanual.io/
Im building an integration between two different API’s. I was given the openAPI spec and instructed to find a mock server generator to get a boilerplate app up. I spent like two hours trying to find some sort of generator that provides value. All the generators I tried seemed half baked (I wanted to use rails for this project, because that’s what I am most familiar developing in. I understand rails is a sub optimal choice for this project.)
In the time I wasted trying to find a generator, I could’ve just wrote the code by hand. Once I just started manually writing code, everything started moving much quicker. Even if I had used a generator, I’d still need to manually update things every time the interface changes, yeah? Who is openAPI for?
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'd like to use.
Here's an example of the type of framework I'm talking about, this is Flask + OpenAPI. https://github.com/zalando/connexion
That said, different strokes for different folks. I am sure it is a massive headache to deal with all that YAML if you're not getting anything out of it.
We're in desperate need of an API documentation solution, and i reached for OpenAPI early on but found it (the UIs availab,e specifically) immensely confusing. It looks great when it's a small flat object, but when you're returning hundreds of unique fields and structures, lots of enums, etc - the result is an automated mess.
I don't think this is strictly a fault of the spec, but of the UI. They seem to design it around the pet shop example, which doesn't seem beneficial to any of our internal, large API responses.
Thoughts?
https://stoplight.io/
I've also written a small custom JS script that generated an OpenAPI spec file by reflecting over some internal data structures, so that's an option as well, and there's lots of tools out there for generating OpenAPI specs based on code (Java annotations, Python models, etc).
You're right that tools are almost all partially-baked.
I use specs to generate data models in TypeScript, Kotlin, and .NET (for different projects). This gives me compile-time guarantees that my API docs match my code.
I also use it for generating documentation and client SDKs in other languages.
If used correctly, it can help automate hundreds or thousands of hours of error-prone work. It also forms an unbreakable contract between systems in totally different languages (not unlike what Protobufs could be used for).
It takes a few hours to find tools you like, but after that, it's generally smooth.
I'm sure there are some client generators out there that work well and create lean code, but it's easy enough to use off-the-shelf HTTP clients with some additional type guards.
This is the tool I use most often for TypeScript: https://github.com/horiuchi/dtsgenerator
The situation is similar in the Java world. It's better to annotate, rather than start with your own spec.
For TypeScript, I mostly use a CLI tool[2] that generates type definitions, which I then use in my routing system and controllers to make sure that any changes to paths, requests, and responses are going to cause compiler errors until they're fixed.
1. https://docs.microsoft.com/en-us/aspnet/core/tutorials/getti...
2. https://github.com/horiuchi/dtsgenerator/
There are tons of hosted solutions for docs (Apimatic, SwaggerHub, Stoplight, and Apicurio Studio).
My favorites are SwaggerHub[2] and Apicurio[3], because their editors are solid and they have good compatibility with all the nooks and crannies of the OpenAPI v3 spec.
1. https://github.com/Redocly/redoc
2. https://swagger.io/tools/swaggerhub
3. https://studio.apicur.io
If you do want a good benefit, here's a testing engine that'll run through an OpenAPI file and confirm the server's adhering to it correctly: https://dredd.org/en/latest/
[0] https://pyotr.readthedocs.io
[1] https://www.starlette.io/
[2] https://www.python-httpx.org/
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 personally see code on the backend as the source of truth
That is a perfectly valid approach, although when you need to coordinate development between multiple teams starting with a specification can be really helpful. That doesn't mean that the spec has to be written once and frozen, as long as everyone is aware of the changes and adapts accordingly.
> Might be worth putting a comparison on your page?
I have indeed started the development when I found that connexion does not completely meet my requirements. The main difference is that pyotr supports ASGI, so can work with any ASGI framework (I haven't tried it with Mangum yet, but am planning to). Additionally, pyotr has a client component, which was inspired by Bravado.
True! I wonder if there's a good way to actually keep teams abreast. I actually end up writing specs by hand from time to time when I just want to get started quickly, but it can be such a pain.
Oh but one of the cool things I was able to set up is automatic generation of client libs (and pushing to a git repo) with GitLab -- it's really awesome to be able to automatically generate client libs that match your API versions.
> I have indeed started the development when I found that connexion does not completely meet my requirements. The main difference is that pyotr supports ASGI, so can work with any ASGI framework (I haven't tried it with Mangum yet, but am planning to). Additionally, pyotr has a client component, which was inspired by Bravado.
So I didn't actually know what ASGI was until I read your existing documentation! I'm not a huge python person but I'd heard of WSGI and some of the other variants but hadn't heard of ASGI! Thanks for the background on the client as well
What I mean is, are people using it in the wild? Are there mature (or at least pretty stable) code generators? Test generators? What's inter-operability like? (Is it easy/possible to generate clients and server stubs in different languages that will work together? Can I write a service, publish my API spec, and expect people to be able to use it to write clients?)
- https://openapi-generator.tech/
- https://github.com/zijianhuang/openapiclientgen
- https://github.com/deepmap/oapi-codegen
I swear I've come across a few others while looking for the best web visualizer (mostly settled on Redoc), but I'm not finding them on https://openapi.tools/ or http://openapi.toolbox.apievangelist.com, so perhaps they've been abandoned
I'm mostly a backend GUI but still interested in learning more about web API. But the only description sentence is presuming that reader is comfortable with a highly specialized jargon. On the other hand I smell that "any project" is probably far narrower than it sound.
> The goal of this project is to create a generator that conveniently creates API definitions in OpenAPI 3 format and then injects the generated YAML file with Swagger UI to any project.
https://www.codenesium.com/projects
https://insomnia.rest/products/designer
The serialiser is predominantly in `internal`, the example is in `api`.
But it's not very fleshed out, without checking thoroughly I think a lot must be unsupported yet.