In the past few years OpenAPI (formerly Swagger) has become a de-facto standard for describing REST APIs, while a format for non-REST APIs is still to be defined.
Various formats do exist though and each project/vendor seems to have their own way of describing their interface:
- The JSON output from the JSDoc3 project comes a long way, but it's primary focus is to generate documentation, not describe the annotated API.
- documentationjs also provides a very good JSON structure, but again the project is more focused on generating documentation.
- esdoc has a very good plugin architecture, outputting a structured JSON should be possible.
- NodeJS has a JSON representation of each one of their modules, e.g. net.html and net.json
- Generate API reference documentation
- Generate typings (TypeScript, Flow etc.)
- Visualize the API to provide an overview
- Assist in API governance by comparing versions and detecting added/deprecated/removed endpoints