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