dotnet core 2.1 에서 Open API(NSwag) 사용하기

install nuget package

Package Manager : Install-Package NSwag.AspNetCore
CLI : dotnet add package NSwag.AspNetCore

NSwag.MSBuild도 나중에 필요할수도 있으니 미리 설치해둔다.

wire up on startup

두곳에 추가해 준다.

public void ConfigureServices(IServiceCollection services)
{
  services.AddSwagger();
...
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
...
  app.UseMvc();

  //app.UseSwaggerReDocWithApiExplorer(settings => Redoc이라는 화면을 보여준다. https://github.com/Rebilly/ReDoc
  app.UseSwaggerUiWithApiExplorer(settings =>
  {
      settings.GeneratorSettings.DefaultPropertyNameHandling = PropertyNameHandling.CamelCase;
  });
}

API Controller

  • 모든 controller에서 다음을 해준다.
  • 리턴 가능한 모든 케이스에 대해 ProducesResponseType을 붙여주자.
  • Consumes도 명시해준다
  • Produces도 명시해준다.
[Consumes("application/vnd.note.create+json")] // post input
[Produces("application/json")]                        // output media type
[ProducesResponseType(typeof(noteDto), 200)]      // output object and return code
[ProducesResponseType(404)]                           // 가능한output return code
[ProducesResponseType(400)]                           // 가능한 output return code

경험상 query (get)을 할때는 Consumes가 필요가 없고 product만 필요함 command(post put patch delete)는 produces를 꼭 넣어주면 좋음.

web browser로 확인을 해보자.

화면에 에러가 나올경우 Url을 아래처럼 넣어보자

https://localhost:44328/swagger/index.html?url=/swagger/v1/swagger.json

vs » project » properties » debug » launch browser: swagger/index.html?url=/swagger/v1/swagger.json 를 추가

nswag 으로 CS 클라이언트 코드를 자동으로 만들어보자.

api를 사용하는 클라이언트가 있다고 하자 여기서는 다른 클라이언트가 있을수도 잇으므로 라이브러리 프로젝트를 하나 만들어서 그걸 클라이언트가 참조하는것으로 한다.

libary project 생성

경로는 c:\SampleApi\Client 이라고 하자

  • new project SampleApi.Client ( dotnet core libary project)
dotnet new classlib
  • 라이브러리 프로젝트에 Newtonsoft.Json 누겟 설치를 해준다.
dotnet add package Newtonsoft.Json

nswag Studio cs 설정

  • namespace : SampleApi.Client
  • generate contracts output : turn on
  • contracts namespace : SampleApi.Client
  • Class stype : poco
  • output file path : c:\SampleApi\Clients\Clients.Generated.cs //전체 경로를 쓴다.
  • contract output file path : c:\SampleApi\Clients\Contracts.Generated.cs //전체 경로를 쓴다.

click Generate Files

파일이 c:\SampleApi\Client\ 여기에 생성이 됬다.

lib를 사용하는 console app 만들기 ( dotnet core console)

  • new project (SampleApi.ConsoleApp))

  • 새 프로젝트가 SampleApi.Client를 레퍼런스 하자.

program.cs를 수정하자.

using SampleApi.Client;
using System;

namespace SampleApi.ConsoleApp
{
    class Program
    {
        static void Main(string[] args)
        {
            Console.WriteLine("Hello World!");
            var client = new ValuesClient();
            var result = client.GetAllAsync().GetAwaiter().GetResult();

            foreach (var item in result)
            {
                Console.WriteLine($"{item.ToJson()}");
            }
        }
    }
}

실행하자.

cd c:\SampleApi\ConsoleApp

dotnet run

결과

Hello World!
{
  "id":"102b9afc-38bd-e711-8f12-00219b8a2e3b",
  "memo":"memo"
}
{
  "id":"202b9afc-38bd-e711-8f12-00219b8a2e3b",
  "memo":"memo"
}

호출하는것을 알수 있다.

nswag Studio TypeScript 설정(Angular)

nswag studio에 typescript에 체크를 한다.

  • module name : shared.service
  • type script : 2.7
  • Generate client class : turn on
  • template : angular
  • rxjs version : 6+
  • http service class : HttpClient
  • token: injectionToken
  • operationClientsFromOperationId : multipleClientsFromOperationId
  • class name : {controller}DataService
  • outputPath: C:\SampleApi\www\src\app\shared\services\memo-dataservice.ts

Generate File을 누른다.

파일이 잘 생성되는지 확인한다.

사용은 다음과 같다. 임포트만해서 사용하면 된다.

import { Component, Inject } from '@angular/core';
import { Http } from '@angular/http';
import { SampleDataService, WeatherForecast } from '../../core/services/api.client.generated';

@Component({
    selector: 'fetchdata',
    templateUrl: './fetchdata.component.html'
})
export class FetchDataComponent {
    public forecasts: WeatherForecast[] | null = [];

    constructor(sampleDataService: SampleDataService) {
        sampleDataService.weatherForecasts().subscribe(fc => {
            this.forecasts = fc;
        });
    }
}

nswag studio를 사용하지 않고 command로 자동화할수 있다.

설정을 nswag로 저장하자.

C:\SampleApi\Client.nswag

npm을 설치하고 실행하면 스튜디어에서 Generate를 클릭한 것과 같은 효과가 있다.

npm install -g nswag
cd C:\SampleApi\
nswag run
teamsmiley's profile image

teamsmiley

2018-10-07 00:00

Read more posts by this author