4 ms·
Swagger ‘documentation’. I understand every programmer I talk to loves this auto generated ‘documentation’ (prolly for selfish reasons). For me the tautologica
by xtiansimon 5y ago
Swagger ‘documentation’.
I understand every programmer I talk to loves this auto generated ‘documentation’ (prolly for selfish reasons). For me the tautological definitions, and lack of overview (which resources you need to form basic reporting—my introduction was swagger api for a Platform POS) undermine the description as ‘documentation’. I’m not complaining about what Swagger does, but about the cavalier way other programmers and vendor managers sound all chipper about their (un-)helpful ‘documentation’.
- nonameiguess 5y agoThe number one thing killing me about auto-generated API documentation is when an API takes a "string" that is really an enum and the generated documentation doesn't list out the enum values. Your only recourse is to read the code if it's open source and available in some obvious place, or hope there's a GUI alternative to the API with a pick list, select every option on the list, and intercept the internal API call it makes to get the string representation of each allowed value. Looking at you, Nexus Repository Manager.
- ldarcyftw 5y agoGraphQL tooling exposes enums as such, I believe