Configuration Steps to enable auto-generation client REST interfaces

Problem Statement:

In the process of developing a multi-layered RESTful system, which includes both backend and frontend components, there is a need to identify new endpoints and update existing ones. It is crucial that these updates are reflected in the RESTful client interface or API client proxy. However, the conventional approach involves manual implementation, resulting in numerous issues such as time wastage, inconsistencies between the API definitions and client representation, and a lack of documentation necessary for proper API utilization.

Proposition:

We propose the implementation of a user-friendly auto-generation system that can simultaneously create a well-documented API client proxy. This solution will involve integrating third-party libraries, executing shell commands, and configuring Visual Studio settings.

Prerequisites:

1. Strongly defined API parameters, including data returned and input model schemas.
2. Strict adherence to RESTful conventions, utilizing HTTP methods to define actions and ensuring that endpoint URIs describe the affected elements.
3. Thorough documentation of the defined API.

Methodology:

1. Enable XML documentation and incorporate it into the OpenAPI configuration.
2. Generate the OpenAPI as a physical JSON file during the project build process.
3. Use AutoRest to generate the API client in a specific output language (in this case, TypeScript) based on the generated OpenAPI JSON file.
4. Copy the commands derived from the previous steps into the post-build event.

Explanation:

In the API project properties, (1) enable the documentation file, and (2) specify the output XML filename and path.

 Source: Adding Swagger to ASP.NET Core Web API Using XML Documentation

Include the on-build generated file in the Swagger configuration to make all documentation references appear in the Swagger UI.

Run the following commands to enable on-build Swagger JSON config file generation and set the path to the Web API project:

• dotnet new tool-manifest
• dotnet tool install --version 5.3.1 Swashbuckle.AspNetCore.Cli Source: How to Generate a Swagger JSON File on Build in .NET Core

To test JSON config file generation, run the following command:

• dotnet swagger tofile --output swagger.json "bin\debug\net7.0\APIs.dll" v1

Install AutoRest using npm:

• npm install -g autorest
• autorest --latest

Generate the AutoRest client using the following command:

• autorest --input-file=swagger.json --typescript --namespace=EarlyRegistration.APIs.Controllers --add-credentials
• If you encounter certification-related errors, try the following steps:
  • Find and delete the file autorest.ps1 in "C:\Users%USERPROFILE%\AppData\Roaming\npm"
  • Execute the command: autorest --reset

If the above steps work as expected, you can copy the commands to the post-build section in the Web API build properties. These commands include:

• dotnet swagger tofile --output swagger.json "bin\debug\net7.0\APIs.dll" v1
• autorest --input-file=swagger.json --output-folder=../../autogen-api-tsclient --typescript --namespace=EarlyRegistration.APIs.Controllers --add-credentials

Build your project, and in the file explorer, you should find a folder named "autogen-api-tsclient" located in the root folder of the project.