Insomnia Designer can help you develop and manage your OpenAPI specs as well :) https://insomnia.rest/products/designer
Thanks, the comment is on topic and could be useful to some, but please mention affiliation when suggesting a product
Show HN: A faster way to prototype your APIs using OpenAPI 3 and Swagger UI
31–40 of 42 posts
Re: Show HN: A faster way to prototype your APIs using OpenAPI 3 and Swagger UI
#32Hey 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) int…
Thanks for the detailed answers!
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!
Re: Show HN: A faster way to prototype your APIs using OpenAPI 3 and Swagger UI
#33Even easier with FastApi https://fastapi.tiangolo.com/ Auto generates both interactive SwaggerUI and Redoc pages. Can turn off before production deployment.
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.
Re: Show HN: A faster way to prototype your APIs using OpenAPI 3 and Swagger UI
#34Shameless 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. [0] https://pyotr.readthedocs.io [1] https://www.starlette.io/ [2] https://www.python-httpx.org/
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?
Re: Show HN: A faster way to prototype your APIs using OpenAPI 3 and Swagger UI
#35Earlier quoted context omitted.
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) int…
Thanks for the detailed answers! 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!
This quote came to my mind after your comment: "It is necessary to light it up so that it shines. (Inscription on Kubachi lamps)".
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.
Re: Show HN: A faster way to prototype your APIs using OpenAPI 3 and Swagger UI
#36Shameless 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. [0] https://pyotr.readthedocs.io [1] https://www.starlette.io/ [2] https://www.python-httpx.org/
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://git…
Thank you for the kind words!
> 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.
Re: Show HN: A faster way to prototype your APIs using OpenAPI 3 and Swagger UI
#37Earlier quoted context omitted.
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://git…
Thank you for the kind words! > 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 compa…
> 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
Re: Show HN: A faster way to prototype your APIs using OpenAPI 3 and Swagger UI
#38Earlier quoted context omitted.
Thanks for the detailed answers! 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!
This quote came to my mind after your comment: "It is necessary to light it up so that it shines. (Inscription on Kubachi lamps)". 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 exampl…
Thanks for going above and beyond on the documentation -- I finally understand exactly where it fits!
Re: Show HN: A faster way to prototype your APIs using OpenAPI 3 and Swagger UI
#39Earlier quoted context omitted.
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.
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.
This is the tool I use most often for TypeScript: https://github.com/horiuchi/dtsgenerator
Re: Show HN: A faster way to prototype your APIs using OpenAPI 3 and Swagger UI
#40Earlier quoted context omitted.
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…
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.
1. https://docs.microsoft.com/en-us/aspnet/core/tutorials/getti...