API specification.json: NSwag Studio has a hard time working with the specification

[ReinderReinders]

I'm not sure yet whether this question falls in the category of: 'the datacontract as described in the api specification.json is incorrect', or 'what tooling should I use to work with this specification?', so I will just describe my problem and hope that others here will have valuable input.

I am implementing a POST on /API/controller/api/v1/subaccount. According to the Swagger API, the success response on a regular call (not erp-background) is a 201 Created with an empty object:

The API specification.json defines this as a "type":"object":

        "responses": {
          "201": {
            "description": "Created",
            "schema": {
              "type": "object"
            }
          },

I am using NSwag Studio v13.18.2.0 to automatically generate a C# client based on the specification.json, since manually implementing all these API calls is a far too time consuming activity (and very vulnerable to backwards incompatible changes).

I am already aware of some compatibility issues since NSwag studio is designed to work with an API built with NSwag, and as far as I am aware the Visma.net API is built using Swashbuckle (the 2 different flavours of Swagger for .net). As far as I know, there is no tool offered by the Swashbuckle framework to generate a client based on a specification.json.

NSwag studio interprets the specification as shown above as returning a non-nullable object (since the property: "nullable":"true" is not present). This means that the generated client, that is generated according to the specs as provided by the Visma.net API, will throw an exception if the object is null:

if (status_ == 201)
{
    var objectResponse_ = await ReadObjectResponseAsync<object>(response_, headers_, cancellationToken).ConfigureAwait(false);
    if (objectResponse_.Object == null)
    {
        throw new ApiException("Response was null which was not expected.", status_, objectResponse_.Text, headers_, null);
    }
    return new Response<object>(status_, headers_, objectResponse_.Object);
}

This means that I have to manually edit the specification.json file in order to generate a working API call, which defeats the purpose of having a generated client in the first place.

There are several options I see how we could interpret this issue:

- It is more in line with OpenApi/Rest standards to return a 204 (NoContent) code on a POST operation without return type. This would be my preferable solution on this and other API calls. A 201 usually returns some properties (such as the Id of the created resource) which is not the case here. See for instance: Status201 

- The specification.json should provide the "nullable":"true" property so that code generators can handle the response object correctly.

- There might be different tooling that works better with the Visma.net API in .net? I am open to suggestions.

[Magnus Johnsen]

Hi,

We'll raise this with the development team.

Thank you. 

[ReinderReinders]

Edit: I am running into the exact same issue with the SubAccount PUT operation, which does return a 204:

"204": {
  "description": "NoContent",
  "schema": {
    "type": "object"
  }

The problem is in the schema definition for the return object. It is not defined as nullable, but it returns null.