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.
Top comments (4)
Are you ultimately planning a specification like WSDL? My favourite feature of WSDL is that you can generate C# classes from the web service definition. A similar thing would be nice in Js/Ts.
I wouldn't really compare it to WSDL - It's more like type definitions in TypeScript, but for JavaScript.
One of biggest issues with typings today is that the majority of them are tediously written by hand, which means that whenever a new version of a library written in JavaScript is published, someone needs to update its typings manually (on e.g. DefinitelyTyped).
By having a specification of the API we could automate the process of generating typings, reference documentation as well as get a quick overview of the API changes between releases.
What do you think of dev.to/orkon/jsx-on-the-backend-3fc3 ?
For REST APIs, it's seems usable for smaller projects. Using JSX over plain JavaScript will most likely introduce some limitations in what is possible.
Regarding the output, keep in mind that API Blueprint is about documenting the API and is not meant to be a description that can be easily consumed by other tools. OpenAPI on the other hand focuses on the description, which you can then use to generate a blueprint document.