Have you looked at some of the language-specific documentation tools for inspiration? I've heard good things about the documentation tooling in #rust and #golang, for example. (I know that #rustdoc supports #markdown and inline testing of code within docs, which seems like it'd be very helpful for API documentation.)
@codesections Yea I use Go documentation + godoc, however lang-specific docs are designed to be used in conjunction with its respective language (obviously) as opposed to being more agnostic like a RESTful API design that could be implemented with one or more languages. Lang-specific docs make the most sense for when you're integrating it directly (package importing, as an example) or for bindings IMO.
That makes sense. I was more thinking in terms of if you do write your own spec—if you wrote something that was basically "godoc for API documentation", then it would *technically* contribute to the yet-another-standard problem, but it might not feel like it was adding something "new" in the same way that a wholly new standard might.
But the use cases might be different enough that that doesn't really work… hmm, not sure.
@codesections Yea if I am going to write some new API design specification, it'll be specifically for RESTful APIs and stray away from being tied to a specific codebase. I think inlining a spec with complex data like JSON schemas, HTTP method specific params, etc. would be a disaster, in addition to likely being harder to parse (needing lang-specific parsers, for example) or to getting multiple parties involved in the design process (handy for contracted design work).
Fosstodon is a Mastodon instance that is open to anyone who is interested in technology; particularly free & open source software.