Towards a JavaScript API Specification

Miralem Drek — Tue, 06 Feb 2018 13:40:28 +0000

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.

This is particularly challenging in dynamically typed languages like JavaScript, which despite its popularity still has no consistent way to describe an API for a consumer.

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

Goal

What I'm interested in is to define a standard for describing JavaScript APIs. By defining a machine-readable format of the consumable API, additional tools can be created based on the provided specification:

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

Much like the Open API specification, I have started with a rough draft of such a format, complemented with a JSON-schema and a tool which can transform JSDoc annotated code to said specification.

Do you think a specification for JavaScript APIs could be useful? Unnecessary? Do you have any feedback on the current draft? Let me know what you think.

DEV Community: Miralem Drek

Towards a JavaScript API Specification

Goal