TIL: NSwag를 사용하여 필수 및 선택적 매개변수 생성

NSwag를 사용하여 각 .NET Core 서비스에 대한 Swagger 페이지를 생성하고 NSwag를 사용하여 다른 서비스가 해당 서비스와 통신할 때 사용할 .NET Standard 프록시 클라이언트를 생성합니다.

그러나 때로는 생성된 클라이언트의 서명이 필요한 매개변수와 null이 될 수 없는 매개변수를 설명하는 데 정확하지 않습니다. 해결 방법입니다.

이것은 예제 엔드포인트입니다. userId 및 age는 필수이며 null을 허용하지 않습니다. faveNumber는 선택 사항이며 null을 허용합니다.

    [HttpGet()]
    public ActionResult GetValues(
        FromHeader] string userId,
        [FromQuery] int age,
        [FromQuery] int? faveNumber)
    {
        return Ok();
    }

생성된 클라이언트 코드에서 다음 메서드 서명을 생성하기를 원합니다.

GetValues(string userId, int age, int? faveNumber = null)

swagger.json 수정

먼저 생성된 swagger.json이 매개변수를 올바르게 설명할 수 있도록 끝점에서 끝점 매개변수를 적절하게 설명해야 합니다.

    "parameters": [
      {
        "name": "userId",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string"
        },
        "x-position": 1
      },
      {
        "name": "age",
        "in": "query",
        "required": true,
        "schema": {
          "type": "integer",
          "format": "int32"
        },
        "x-position": 2
      },
      {
        "name": "faveNumber",
        "in": "query",
        "schema": {
          "type": "integer",
          "format": "int32",
          "nullable": true
        },
        "x-position": 3
      }
    ],

필수 필드와 널 입력 가능 필드는 제대로 생성된 클라이언트를 가져오는 열쇠입니다. Nullable(?)을 사용하여 nullable인 매개변수를 표시하고 BindRequired를 사용하여 포함되어야 하는 매개변수를 표시합니다.

    [HttpGet()]
    public ActionResult GetValues(
        [BindRequired][FromHeader] string userId,
        [BindRequired][FromQuery] int age,
        [FromQuery] int? faveNumber)
    {
        return Ok();
    }
}

Startup.cs에서 기본 null 참조를 NotNull로 설정하면 필수 필드에서 null을 값으로 허용하지 않습니다.

    services.AddOpenApiDocument(settings =>

    {

        settings.DefaultReferenceTypeNullHandling = NJsonSchema.Generation.ReferenceTypeNullHandling.NotNull;

    });

클라이언트 생성

이제 적절한 swagger.json이 있으므로 이를 사용하여 NSwag 클라이언트를 빌드합니다.

"옵션 매개변수 생성"설정이 선택되어 있는지 확인하십시오. 다음 방법으로 생성된 클라이언트로 끝납니다.

    public async System.Threading.Tasks.Task<FileResponse> Values_GetValuesAsync(

        string userId, 

        int age, 

        int? faveNumber = null))

요약

NSwag 클라이언트를 생성할 때 클라이언트 생성 설정만 사용하지 말고 생성되는 swagger.json이 코드에서 빌드한 끝점을 올바르게 나타내는지 확인하세요.

올바른 swagger.json을 빌드하는 것은 올바른 클라이언트를 빌드하는 데 중요합니다.