vscode-azurekudu

VSCode Azure SDK for Node.js - KuduClient

This package provides an automatically generated typescript client for Kudu.

Concepts

• Swagger: A tool for describing and debugging REST APIs. For ASP.NET projects, you add swagger with this single nuget package.
• AutoRest: A tool for creating client libraries for REST APIs. In this repo, we give it a swagger.json file and it creates a typescript client.

Development

This package will not work in many cases because the Kudu repo is missing important metadata. It is slowly improving on an as-needed basis (largely driven by a few App Service extensions in VS Code). To make changes to the package, follow these steps:

1. Clone the forked version of Kudu that has Swagger enabled
2. Make your changes to the swagger config file or take a look at the common fixes below.
3. To setup Kudu, follow Kudu's Getting started guide.
4. Run Kudu, create a new application, and navigate to the swagger endpoint (It will be a url similar to http://localhost:16167/swagger/docs/v1, but the port will likely be different)
5. Copy the generated json to the swagger.json file in this repo.
6. Run npm run build to generate your typescript client library from the updated swagger.json.

NOTE: It might be easier to manually edit the 'swagger.json' file when you're debugging this package. However, you should always make the corresponding change in the Kudu repo so that we can continue to automatically generate the swagger.json file.

Common Fixes

1. Most of the generated typescript methods return a generic 'object'. You must add a ResponseType in the Kudu repo to actually get helpful types:

   using System.Web.Http.Description; // <-- This line must be added
   
   class ExampleController
   {
       [HttpGet]
       [ResponseType(typeof(Person))] // <-- This line must be added
       public async Task<HttpResponseMessage> GetPerson()
       {
           return Request.CreateResponse(HttpStatusCode.OK, new Person('Nathan'));
       }
   }
   

2. Autorest assumes all responses are 'JSON' and does not support other types (See this issue). If a call returns something other than JSON, you must specify a return type of 'void' ([ResponseType(typeof(void))]) to avoid a JSON parse error and handle the response yourself.

Troubleshooting

1. If Kudu returns a 500 error when creating an application, verify that your kudu repo is located in a directory that has read-access. Creation will fail if it cannot read the config file.

License

MIT