- 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?
1. Construct schema objects and request objects using Python classes with marshmallow  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?
> - Does it wrap an existing application?
If you meant if this is a wrapper for other apps then it is. These two: marshmallow  and apispec 
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 , flask-swagger  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.
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  and convert content of API spec in OpenAPI 3 format to Swagger 2.
Then download an executable file of go-swagger  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.
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):
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.
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.
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 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.
There are tons of hosted solutions for docs (Apimatic, SwaggerHub, Stoplight, and Apicurio Studio).
My favorites are SwaggerHub and Apicurio, because their editors are solid and they have good compatibility with all the nooks and crannies of the OpenAPI v3 spec.
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/
Other than that, library looks cool! like connexion 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.
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?)
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.
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.