Do API docs actually provide much benefit in practice? Does anyone actually use Javadocs, for example? The problem with documentation at this level is that it's too low level. It useful, maybe, as a quick reference once you already know the project.
I'm less familiar with JSON API, but at first glance it looks like a standard around JSON response bodies for APIs.
Swagger's standard API definition is external of your actual API responses and is used primarily for API docs and can be used for auto generating API client libraries/SDKs.
I'm sorry to be negative, but the moment I saw this article I knew I'd see a reference to this cartoon. I assume 98% of HN readers have seen it (too) many times.
Comments
Do API docs actually provide much benefit in practice? Does anyone actually use Javadocs, for example? The problem with documentation at this level is that it's too low level. It useful, maybe, as a quick reference once you already know the project.
How does this compare to JSON API? http://jsonapi.org/
Is this a competing standard? I'm getting fairly nervous about the rise of competing "standards" with APIs.
I'm less familiar with JSON API, but at first glance it looks like a standard around JSON response bodies for APIs.
Swagger's standard API definition is external of your actual API responses and is used primarily for API docs and can be used for auto generating API client libraries/SDKs.
Here's an example:
https://github.com/OAI/OpenAPI-Specification/blob/master/exa...
Relevant XKCD: https://xkcd.com/927/
Except this is not a new standard. OAI is swagger, converted into a more open standard than before.
Relevant dictionary:
trite
adjective
(of a remark, opinion, or idea) overused and consequently of little import; lacking originality or freshness.
I'm sorry to be negative, but the moment I saw this article I knew I'd see a reference to this cartoon. I assume 98% of HN readers have seen it (too) many times.