3 ms·
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, Ko
by smt88 6y ago
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 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.
- rolha-capoeira 6y agoWhat tools do you use?
- smt88 6y agoSee sibling comments for some links
- 0xffff2 6y agoI 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.
- smt88 6y agoFor .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/getting-started-with-nswag?view=aspnetcore-3.1&tabs=visual-studio https://docs.microsoft.com/en-us/aspnet/core/tutorials/getti... 2. https://github.com/horiuchi/dtsgenerator/ https://github.com/horiuchi/dtsgenerator/
- acemarke 6y agoWhat'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.
- smt88 6y agoI 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 https://github.com/horiuchi/dtsgenerator
- ccleve 6y agoHow do you use it for generating documentation? Can you generate anything other than Swagger UI for API docs?
- smt88 6y agoThe 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. 1. https://github.com/Redocly/redoc https://github.com/Redocly/redoc 2. https://swagger.io/tools/swaggerhub https://swagger.io/tools/swaggerhub 3. https://studio.apicur.io https://studio.apicur.io