stefh / restease-client-generator

A Visual Studio Extension to generate a RestEase compatible client based on a Swagger / OpenAPI specification files

RestEase-Client-Generator

Generate a RestEase compatible client (Interface & Models) based on a Swagger / OpenApi or RAML specification.

1️⃣ NuGet Package

2️⃣ dotnet tool

Installation & Usage

3️⃣ Visual Studio Extension

Features

• Supports Visual Studio 2017 and 2019
• Add New RestEase API Client to a project from an OpenAPI specification URL (e.g https://petstore.swagger.io/v2/swagger.json)
• Define custom namespace for the generated file
• Auto-updating of generated code file when changes are made to the specification file (.json, .yml, .yaml, .raml)
• This Visual Studio Extension will automatically add the required nuget packages that the generated code depends on.

Installation & Usage

Options

See https://github.com/StefH/RestEase-Client-Generator/wiki/Options

---

Demo

Blazor WebAssembly Demo

Example

Input Yaml file 'PetStore.yaml'

Excerpt...

paths:
  /pet:
    post:
      tags:
        - pet
      summary: Add a new pet to the store
      description: ''
      operationId: addPet
      consumes:
        - application/json
        - application/xml
      produces:
        - application/xml
        - application/json
      parameters:
        - in: body
          name: body
          description: Pet object that needs to be added to the store
          required: true
          schema:
            $ref: '#/definitions/Pet'

(Full example).

Generate file 'PetStore.cs'

Excerpt...

namespace RestEaseClientGeneratorConsoleApp.PetStoreJson.Api
{
    public interface IPetStoreApi
    {
        /// <summary>
        /// Add a new pet to the store
        /// </summary>
        /// <param name="pet">A pet for sale in the pet store</param>
        [Post("/pet")]
        Task AddPetAsync([Body] Pet pet);

        // More methods ...
    }
}

namespace RestEaseClientGeneratorConsoleApp.PetStoreJson.Models
{
    public class Pet
    {
        public long Id { get; set; }

        // More properties ...
    }
}

(Full example).

Create a Client and call methods

var petStoreApi = RestClient.For<IPetStoreApi>("https://petstore.swagger.io/v2");

var findPetsByTags = await petStoreApi.FindPetsByTagsAsync(new[] { "cat" });

Screenshots

Add new specification and generate client code

Generate client code for existing .json, .yml or .yaml file

Credits

• Project source code is based on REST API Client Code Generator
• Code used from https://raw.githubusercontent.com/andeart/CaseConversions/master/CaseConversions/CaseConversion.cs
• Code used from https://www.codeproject.com/articles/6294/description-enum-typeconverter

restease-client-generator's Issues

Upgrade from this tool in VS does not work?

Some issues with naming and other feedback...

I tried to generate a client for the Jira api - https://developer.atlassian.com/cloud/jira/platform/swagger-v3.v3.json

Its a bit of a beast and throws up some issues that would be nice if they could be handled...

• some types like AvatarUrlsBean has properties with names like 16x16, 24x24 etc, these don't map to valid c# property names
• some types have properties with the same name as the type, e.g. IssueLinkTypes has a property issueLinkTypes which becomes IssueLinkTypes in the generated class, not valid in c#
• this highlights a general issue with naming: as the property name is changed to be uppercase, a json property name attribute should probably be applied on the generated property
• on the organisation side, it would be nice if the generated model classes were split into separate files and into a models folder, possibly even further split into sub-folders based on the api structure but I guess that could get messy quickly
• some type names result in ambiguous references, e.g. there is a generated class named Version with clashes with System.Version, possibly use some using alias for known system types
• some methods accepting multi-part form data have resulted in incomplete extension methods ,e.g.

public static Task SetColumnsAsync(this IJiraApi api, string contentType, long id)
        {
            return api.SetColumnsAsync(contentType, id, content);
        }

That's as far as I've got just now to get to the point of a solution that builds, I'll try and give some more feedback as I try to get to a working solution.

Generate from right-click menu on YAML file works only once

I was able to generate client C# code only once. After that clicking "Generate" on same YAML file does nothing. No window, no information what went wrong.

What i tried and didn't help:

• VS restart
• PC restart
• removing generated .cs file
• removing generated .cs record in .csproj file

Visual studio professional 2019 v16.11.1

formData is not correctly generated

"post": {
    "tags": [ "pet" ],
    "summary": "Updates a pet in the store with form data",
    "description": "",
    "operationId": "updatePetWithForm",
    "consumes": [ "application/x-www-form-urlencoded" ],
    "produces": [ "application/json", "application/xml" ],
    "parameters": [
      {
        "name": "petId",
        "in": "path",
        "description": "ID of pet that needs to be updated",
        "required": true,
        "type": "integer",
        "format": "int64"
      },
      {
        "name": "name",
        "in": "formData",
        "description": "Updated name of the pet",
        "required": false,
        "type": "string"
      },
      {
        "name": "status",
        "in": "formData",
        "description": "Updated status of the pet",
        "required": false,
        "type": "string"
      }
    ],
    "responses": { "405": { "description": "Invalid input" } },
    "security": [ { "petstore_auth": [ "write:pets", "read:pets" ] } ]
  }

C# code:

/// <summary>
/// Updates a pet in the store with form data
/// </summary>
/// <param name="petId">ID of pet that needs to be updated</param>
[Post("/pet/{petId}")]
Task UpdatePetWithFormAsync([Path] long petId);