- 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
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!
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...
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.
Thoughts?
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.
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[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.
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.
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.
