Proposal: VSCode command to download OpenAPI specification

[shafreenAnfar]

Summary

Ballerina HTTP service automatically generates the service description for each service. But there is no convenient way to retrieve it. This proposal is to address this concern.

Goals

• Provide an convenient way to download OpenAPI specification

Motivation

As mentioned is the summary section, Ballerina HTTP services automatically generates service description for each service. The service description is captured in the form of OpenAPI Specification (OAS). However, to get the OAS you need to do the below.

Consider a service running on path foo.

curl host:9000/foo -v -X OPTIONS

HTTP/1.1 204 No Content
allow: OPTIONS, GET, HEAD, POST
date: Thu, 13 Oct 2016 11:45:00 GMT
server: ballerina
link: </foo/openapi-doc-dygixywsw>;rel="openapi-doc"

Once discovered user has to do the following.

curl host:9000/foo/openapi-doc-dygixywsw

NOTE: Related issue #1616

This can be simplified with a VSCode command as explained in the section.

Description

VSCode commands allows you to codify small work of units. Ballerina already has such commands.

Similarly, another command named Ballerina: Download OpenAPI Specification can be added to the pallet. This command can simply download the service description from a given HTTP service. The command should take the URL of the service as the input.

Once executed, it should create a service-desc.yaml file with the OAS content in the root of the project directory.