Anyone got experience with automatic api description generators (like Swagger)?
-
So there's a push in my company for better documentation. And part of that is documenting the "REST" (ok, really just HTTP apis that use vaguely REST-like semantics) API for the various services. The architect wants us to maintain those by hand. Which is something we've failed at in the past because it's quite cumbersome. And the resulting Confluence tables are painful to read (mostly due to formatting, plus Confluence...).
So I was thinking that it might make more sense to implement some kind of OpenApi-style documentation/structure, especially if it can be generated from existing endpoints (of which there are many) and the job be re-run as part of container build when we deploy a new version. I know swagger has various products in this field, but there might be others. Sure, there might be some manual touchups, but that'd give us at least the basic endpoints as a framework in a way that's much easier to read and deal with.
Does anyone have experience with these? Do they work? Are they painful to deal with? Are they worth it?
Same goes for more general documentation-generation products. I really don't want to have to spend my time doing documentation that's just reproducing what the code and in-code documentation says--if I have to write documentation (which I do), it should be higher level and explain why and how to use various bits, as well as the caveats and gotchas that inevitably arise.
-
@Benjamin-Hall I wrote a thing to automatically add Swagger (with a patch) to our applications via a library, so, yes. From the code-first side, publishing API docs & soundboard. There's also a spec-first approach. Not just for clients, either, b/c standard sharkjumping hubris.
If you're not constrained on artifacts, springfox publishes an all-in-one.
You get places to describe endpoints, models, and fields, tho all the terminology is imo pretty bad around each of those. Describing orchestrations, you may be able to do with group descriptions.
ed. you know he has you blocked, right?
I sure do, Ed.
-
@Benjamin-Hall I use Swagger every day. We use this because our CS is C#/VS, and our front-end is made with PEGA. Since we can't debug the whole application in VS, Swagger at least gives us a way to run the services in debug mode.
So a common scenario is that I get the Pega team to give us the parameters that are being passed to the service as well as the name of the service that's being called. So Swagger is pretty good as a workaround, though of course not as good as being able to run the application directly in VS.
I guess that Swagger is what's documenting the services. In Swagger, you can see the generated comments. Your company may want additional human-generated comments as well.
I hate when people reply to a question without actually addressing the question, but I hope that this at least touches on your question.
-
I've written API documentation in Swagger and OpenApi, and others further back. I'm a bit ambivalent about the Swagger and OpenApi style, since they about double the size of code in the API bits if you want any sort of useful documentation out of it that actually will be useful for understanding the API.
I still tend to use them though, since there is a greater chance of me updating API documentation if it's in the code, rather than on some crusty document store somewhere that is moved every two or three years.
-
@Carnage said in Anyone got experience with automatic api description generators (like Swagger)?:
the Swagger and OpenApi style, since they about double the size of code in the API bits if you want any sort of useful documentation out of it
Since my controllers only and strictly delegate immediately to single business services, this ratio is far worse for me.
-
@Gribnit said in Anyone got experience with automatic api description generators (like Swagger)?:
@Carnage said in Anyone got experience with automatic api description generators (like Swagger)?:
the Swagger and OpenApi style, since they about double the size of code in the API bits if you want any sort of useful documentation out of it
Since my controllers only and strictly delegate immediately to single business services, this ratio is far worse for me.
Yeah that's true. And the POJOs tend to get full of stuff too.
-
@Benjamin-Hall said in Anyone got experience with automatic api description generators (like Swagger)?:
Does anyone have experience with these? Do they work? Are they painful to deal with? Are they worth it?
I use Swagger, connected to my JAX-RS API via annotations on the interfaces (as well as normal documentation generation from doc comments). It bloats those interfaces, but they're quite a small part of the overall code; I don't need to change them very often. The result is... imperfect, but
means I'm definitely not going to do anything better, and I document things way better than the rest of my team because I feel that docs are important. (Yes, we have a contractual obligation to produce docs. I was so glad when that was slipped in and we could just say "yep, already got that".)The pain was irritating when getting them first set up, but after that it has been fine.
Same goes for more general documentation-generation products. I really don't want to have to spend my time doing documentation that's just reproducing what the code and in-code documentation says--if I have to write documentation (which I do), it should be higher level and explain why and how to use various bits, as well as the caveats and gotchas that inevitably arise.
You need many sorts of documentation in general. Manuals, tutorials, maintenance guides, management summaries, etc. Automated tooling can only help with some of that; ultimately, you have to knuckle down and write. No way around it; job isn't done until you do.
-
@Gribnit said in Anyone got experience with automatic api description generators (like Swagger)?:
@Benjamin-Hall I wrote a thing to automatically add Swagger (with a patch) to our applications via a library, so, yes. From the code-first side, publishing API docs & soundboard. There's also a spec-first approach. Not just for clients, either, b/c standard sharkjumping hubris.
If you're not constrained on artifacts, springfox publishes an all-in-one.
You get places to describe endpoints, models, and fields, tho all the terminology is imo pretty bad around each of those. Describing orchestrations, you may be able to do with group descriptions.
ed. you know he has you blocked, right?
I sure do, Ed.
FFS Gribnit. You post something coherent and you break the css for your post on mobile.
Avatar and the next line should be on the same line!
