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.
Show HN: A faster way to prototype your APIs using OpenAPI 3 and Swagger UI
21–30 of 42 posts
Re: Show HN: A faster way to prototype your APIs using OpenAPI 3 and Swagger UI
#22Hey 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 mo…
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.
[1]: https://marshmallow.readthedocs.io/en/stable/
[2]: https://github.com/marshmallow-code/apispec
Re: Show HN: A faster way to prototype your APIs using OpenAPI 3 and Swagger UI
#23Even easier with FastApi https://fastapi.tiangolo.com/ Auto generates both interactive SwaggerUI and Redoc pages. Can turn off before production deployment.
Seconded. FastAPI has been a boon for us in our project work and the auto-generated documentation is one of its very best features.
Re: Show HN: A faster way to prototype your APIs using OpenAPI 3 and Swagger UI
#24Even easier with FastApi https://fastapi.tiangolo.com/ Auto generates both interactive SwaggerUI and Redoc pages. Can turn off before production deployment.
Came here to say this, FastApi was my introduction to Swagger and now I love it!
Re: Show HN: A faster way to prototype your APIs using OpenAPI 3 and Swagger UI
#25I 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.
Re: Show HN: A faster way to prototype your APIs using OpenAPI 3 and Swagger UI
#26Earlier quoted context omitted.
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…
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 st…
I tried out Stoplight Studio last year as a GUI for creating OpenAPI specs, and was pretty pleased with it:
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).
Re: Show HN: A faster way to prototype your APIs using OpenAPI 3 and Swagger UI
#27As 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, be…
I have extensively used OpenAPI Specs for years. 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 o…
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.
Re: Show HN: A faster way to prototype your APIs using OpenAPI 3 and Swagger UI
#28Just a heads up, there are a number of similar/identically named projects:
- 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
Re: Show HN: A faster way to prototype your APIs using OpenAPI 3 and Swagger UI
#29Insomnia Designer can help you develop and manage your OpenAPI specs as well :)
Re: Show HN: A faster way to prototype your APIs using OpenAPI 3 and Swagger UI
#30As 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, be…
I have extensively used OpenAPI Specs for years. 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 o…
How do you use it for generating documentation? Can you generate anything other than Swagger UI for API docs?