NSwag 및 ASP.NET Core 시작Get started with NSwag and ASP.NET Core

작성자: Christoph Nienaber, Rico SuterDave BrockBy Christoph Nienaber, Rico Suter, and Dave Brock

NSwag는 다음 기능을 제공합니다.NSwag offers the following capabilities:

  • Swagger UI 및 Swagger 생성기를 사용하는 기능The ability to utilize the Swagger UI and Swagger generator.
  • 유연한 코드 생성 기능Flexible code generation capabilities.

NSwag를 사용하면 기존 API가 필요하지 않으므로 Swagger를 통합하고 클라이언트 구현을 생성하는 타사 API를 사용할 수 있습니다.With NSwag, you don't need an existing API—you can use third-party APIs that incorporate Swagger and generate a client implementation. NSwag를 사용하면 개발 주기를 단축하고 API 변경에 쉽게 대응할 수 있습니다.NSwag allows you to expedite the development cycle and easily adapt to API changes.

NSwag 미들웨어 등록Register the NSwag middleware

다음 작업을 수행하려면 NSwag 미들웨어를 등록합니다.Register the NSwag middleware to:

  • 구현된 Web API에 대한 Swagger 사양을 생성합니다.Generate the Swagger specification for the implemented web API.
  • Web API를 찾아보고 테스트하는 Swagger UI를 제공합니다.Serve the Swagger UI to browse and test the web API.

NSwag ASP.NET Core 미들웨어를 사용하려면 NSwag.AspNetCore NuGet 패키지를 설치합니다.To use the NSwag ASP.NET Core middleware, install the NSwag.AspNetCore NuGet package. 이 패키지에는 Swagger 사양, Swagger UI(v2 및 v3) 및 ReDoc UI를 생성하고 제공하는 미들웨어가 포함되어 있습니다.This package contains the middleware to generate and serve the Swagger specification, Swagger UI (v2 and v3), and ReDoc UI.

다음 방법 중 하나를 사용하여 NSwag NuGet 패키지를 설치합니다.Use one of the following approaches to install the NSwag NuGet package:

  • 패키지 관리자 콘솔 창에서:From the Package Manager Console window:

    • 보기 > 다른 창 > 패키지 관리자 콘솔 로 이동Go to View > Other Windows > Package Manager Console

    • TodoApi.csproj 파일이 위치한 디렉터리로 이동Navigate to the directory in which the TodoApi.csproj file exists

    • 다음 명령을 실행합니다.Execute the following command:

      Install-Package NSwag.AspNetCore
      
  • NuGet 패키지 관리 대화 상자에서:From the Manage NuGet Packages dialog:

    • 솔루션 탐색기 > NuGet 패키지 관리 에서 프로젝트를 마우스 오른쪽 단추로 클릭Right-click the project in Solution Explorer > Manage NuGet Packages
    • 패키지 소스 를 “nuget.org”로 설정Set the Package source to "nuget.org"
    • 검색 상자에 “NSwag.AspNetCore” 입력Enter "NSwag.AspNetCore" in the search box
    • 찾아보기 탭에서 "NSwag.AspNetCore" 패키지를 선택하고 설치 클릭Select the "NSwag.AspNetCore" package from the Browse tab and click Install

Swagger 미들웨어 추가 및 구성Add and configure Swagger middleware

다음 단계를 수행하여 ASP.NET Core 앱에서 Swagger를 추가하고 구성합니다.Add and configure Swagger in your ASP.NET Core app by performing the following steps:

  • Startup.ConfigureServices 메서드에서 필수 Swagger 서비스를 등록합니다.In the Startup.ConfigureServices method, register the required Swagger services:
public void ConfigureServices(IServiceCollection services)
{
    services.AddDbContext<TodoContext>(opt =>
        opt.UseInMemoryDatabase("TodoList"));
    services.AddMvc();

    // Register the Swagger services
    services.AddSwaggerDocument();
}
  • Startup.Configure 메서드에서 생성된 Swagger 사양 및 Swagger UI를 지원하기 위해 미들웨어를 사용하도록 설정합니다.In the Startup.Configure method, enable the middleware for serving the generated Swagger specification and the Swagger UI:
public void Configure(IApplicationBuilder app)
{
    app.UseStaticFiles();

    // Register the Swagger generator and the Swagger UI middlewares
    app.UseOpenApi();
    app.UseSwaggerUi3();

    app.UseMvc();
}
  • 앱을 시작합니다.Launch the app. 다음으로 이동합니다.Navigate to:
    • http://localhost:<port>/swagger - Swagger UI를 봅니다.http://localhost:<port>/swagger to view the Swagger UI.
    • http://localhost:<port>/swagger/v1/swagger.json - Swagger 사양을 봅니다.http://localhost:<port>/swagger/v1/swagger.json to view the Swagger specification.

코드 생성Code generation

다음 옵션 중 하나를 선택하여 NSwag의 코드 생성 기능을 활용할 수 있습니다.You can take advantage of NSwag's code generation capabilities by choosing one of the following options:

NSwagStudio로 코드 생성Generate code with NSwagStudio

  • NSwagStudio GitHub 리포지토리의 지침에 따라 NSwagStudio를 설치합니다.Install NSwagStudio by following the instructions at the NSwagStudio GitHub repository. NSwag 릴리스 페이지에서 설치 및 관리자 권한 없이 시작할 수 있는 xcopy 버전을 다운로드할 수 있습니다.On the NSwag release page you can download an xcopy version which can be started without installation and admin privileges.

  • NSwagStudio를 시작하고 Swagger 사양 URL 텍스트 상자에 swagger.json 파일 URL을 입력합니다.Launch NSwagStudio and enter the swagger.json file URL in the Swagger Specification URL text box. 예를 들어 http://localhost:44354/swagger/v1/swagger.json 와 같습니다.For example, http://localhost:44354/swagger/v1/swagger.json.

  • 로컬 복사본 만들기 단추를 클릭하여 Swagger 사양의 JSON 표시를 생성합니다.Click the Create local Copy button to generate a JSON representation of your Swagger specification.

    Swagger 사양의 로컬 복사본 만들기

  • 출력 영역에서 CSharp 클라이언트 확인란을 클릭합니다.In the Outputs area, click the CSharp Client check box. 프로젝트에 따라 TypeScript 클라이언트 또는 CSharp 웹 API 컨트롤러 를 선택할 수도 있습니다.Depending on your project, you can also choose TypeScript Client or CSharp Web API Controller. CSharp 웹 API 컨트롤러 를 선택하면 서비스 사양에서 역방향 생성으로 사용되는 서비스를 다시 빌드합니다.If you select CSharp Web API Controller, a service specification rebuilds the service, serving as a reverse generation.

  • 출력 생성 을 클릭하여 TodoApi.NSwag 프로젝트의 완전한 C# 클라이언트 구현을 생성합니다.Click Generate Outputs to produce a complete C# client implementation of the TodoApi.NSwag project. 생성된 클라이언트 코드를 보려면 CSharp 클라이언트 탭을 클릭합니다.To see the generated client code, click the CSharp Client tab:

//----------------------
// <auto-generated>
//     Generated using the NSwag toolchain v12.0.9.0 (NJsonSchema v9.13.10.0 (Newtonsoft.Json v11.0.0.0)) (http://NSwag.org)
// </auto-generated>
//----------------------

namespace MyNamespace
{
    #pragma warning disable

    [System.CodeDom.Compiler.GeneratedCode("NSwag", "12.0.9.0 (NJsonSchema v9.13.10.0 (Newtonsoft.Json v11.0.0.0))")]
    public partial class TodoClient
    {
        private string _baseUrl = "https://localhost:44354";
        private System.Net.Http.HttpClient _httpClient;
        private System.Lazy<Newtonsoft.Json.JsonSerializerSettings> _settings;

        public TodoClient(System.Net.Http.HttpClient httpClient)
        {
            _httpClient = httpClient;
            _settings = new System.Lazy<Newtonsoft.Json.JsonSerializerSettings>(() =>
            {
                var settings = new Newtonsoft.Json.JsonSerializerSettings();
                UpdateJsonSerializerSettings(settings);
                return settings;
            });
        }

        public string BaseUrl
        {
            get { return _baseUrl; }
            set { _baseUrl = value; }
        }

        // code omitted for brevity

C# 클라이언트 코드는 설정 탭의 선택에 따라 생성됩니다. 기본 네임 스페이스 이름 바꾸기 및 동기 메서드 생성 등의 작업을 수행하도록 설정을 수정합니다.The C# client code is generated based on selections in the Settings tab. Modify the settings to perform tasks such as default namespace renaming and synchronous method generation.

  • API를 사용할 클라이언트 프로젝트의 파일에 생성된 C# 코드를 복사합니다.Copy the generated C# code into a file in the client project that will consume the API.
  • Web API를 사용하기 시작합니다.Start consuming the web API:
 var todoClient = new TodoClient();

// Gets all to-dos from the API
 var allTodos = await todoClient.GetAllAsync();

 // Create a new TodoItem, and save it via the API.
var createdTodo = await todoClient.CreateAsync(new TodoItem());

// Get a single to-do by ID
var foundTodo = await todoClient.GetByIdAsync(1);

API 문서 사용자 지정Customize API documentation

Swagger는 Web API를 보다 쉽게 사용하도록 개체 모델을 문서화하는 옵션을 제공합니다.Swagger provides options for documenting the object model to ease consumption of the web API.

API 정보 및 설명API info and description

Startup.ConfigureServices 메서드에서 AddSwaggerDocument 메서드에 전달되는 구성 작업은 작성자, 라이선스 및 설명과 같은 정보를 추가합니다.In the Startup.ConfigureServices method, a configuration action passed to the AddSwaggerDocument method adds information such as the author, license, and description:

services.AddSwaggerDocument(config =>
{
    config.PostProcess = document =>
    {
        document.Info.Version = "v1";
        document.Info.Title = "ToDo API";
        document.Info.Description = "A simple ASP.NET Core web API";
        document.Info.TermsOfService = "None";
        document.Info.Contact = new NSwag.OpenApiContact
        {
            Name = "Shayne Boyer",
            Email = string.Empty,
            Url = "https://twitter.com/spboyer"
        };
        document.Info.License = new NSwag.OpenApiLicense
        {
            Name = "Use under LICX",
            Url = "https://example.com/license"
        };
    };
});

Swagger UI는 버전의 정보를 표시합니다.The Swagger UI displays the version's information:

버전 정보를 포함한 Swagger UI

XML 주석XML comments

XML 주석을 사용하려면 다음 단계를 수행합니다.To enable XML comments, perform the following steps:

  • 솔루션 탐색기 에서 프로젝트를 마우스 오른쪽 단추로 클릭하고 <project_name>.csproj 편집 을 선택합니다.Right-click the project in Solution Explorer and select Edit <project_name>.csproj.
  • 강조 표시된 줄을 .csproj 파일에 수동으로 추가합니다.Manually add the highlighted lines to the .csproj file:
<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>
  • 솔루션 탐색기 에서 프로젝트를 마우스 오른쪽 단추로 클릭하고 속성 선택Right-click the project in Solution Explorer and select Properties
  • 빌드 탭의 출력 섹션에서 XML 문서 파일 상자 선택Check the XML documentation file box under the Output section of the Build tab

데이터 주석Data annotations

NSwag는 리플렉션을 사용하고 웹 API 작업의 권장 반환 형식은 IActionResult이므로 작업이 수행 중인 작업과 반환 결과를 유추할 수 없습니다.Because NSwag uses Reflection, and the recommended return type for web API actions is IActionResult, it can't infer what your action is doing and what it returns.

다음 예제를 참조하세요.Consider the following example:

[HttpPost]
public IActionResult Create([FromBody] TodoItem item)
{
    if (item == null)
    {
        return BadRequest();
    }

    _context.TodoItems.Add(item);
    _context.SaveChanges();

    return CreatedAtRoute("GetTodo", new { id = item.Id }, item);
}

이전 작업은 IActionResult를 반환하지만 작업 내에서는 CreatedAtRoute 또는 BadRequest를 반환합니다.The preceding action returns IActionResult, but inside the action it's returning either CreatedAtRoute or BadRequest. 데이터 주석을 사용하여 이 작업이 반환하는 것으로 알려진 HTTP 상태 코드를 클라이언트에 알립니다.Use data annotations to tell clients which HTTP status codes this action is known to return. 다음 특성을 사용하여 작업을 표시합니다.Mark the action with the following attributes:

[ProducesResponseType(typeof(TodoItem), StatusCodes.Status201Created)]  // Created
[ProducesResponseType(StatusCodes.Status400BadRequest)]                 // BadRequest

NSwag는 리플렉션을 사용하고 웹 API 작업의 권장 반환 형식은 ActionResult<T>이므로 T로 정의된 반환 형식만 유추할 수 있습니다.Because NSwag uses Reflection, and the recommended return type for web API actions is ActionResult<T>, it can only infer the return type defined by T. 다른 가능한 반환 형식은 자동으로 유추할 수 없습니다.You can't automatically infer other possible return types.

다음 예제를 참조하세요.Consider the following example:

[HttpPost]
public ActionResult<TodoItem> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    _context.SaveChanges();

    return CreatedAtRoute("GetTodo", new { id = item.Id }, item);
}

이전 작업이 ActionResult<T>를 반환합니다.The preceding action returns ActionResult<T>. 작업 내에서 CreatedAtRoute를 반환합니다.Inside the action, it's returning CreatedAtRoute. 컨트롤러에는 [ApiController] 특성이 있으므로 BadRequest 응답도 가능합니다.Since the controller has the [ApiController] attribute, a BadRequest response is possible, too. 자세한 정보는 자동 HTTP 400 응답을 참조하세요.For more information, see Automatic HTTP 400 responses. 데이터 주석을 사용하여 이 작업이 반환하는 것으로 알려진 HTTP 상태 코드를 클라이언트에 알립니다.Use data annotations to tell clients which HTTP status codes this action is known to return. 다음 특성을 사용하여 작업을 표시합니다.Mark the action with the following attributes:

[ProducesResponseType(StatusCodes.Status201Created)]     // Created
[ProducesResponseType(StatusCodes.Status400BadRequest)]  // BadRequest

ASP.NET Core 2.2 이상에서는 [ProducesResponseType]을 사용하여 명시적으로 개별 작업을 데코레이트하는 대신 규칙을 사용할 수 있습니다.In ASP.NET Core 2.2 or later, you can use conventions instead of explicitly decorating individual actions with [ProducesResponseType]. 자세한 내용은 웹 API 규칙 사용를 참조하세요.For more information, see 웹 API 규칙 사용.

이제 Swagger 생성기는 이 작업을 정확하게 설명할 수 있으며, 생성된 클라이언트가 엔드포인트를 호출할 때 수신한 내용을 알 수 있습니다.The Swagger generator can now accurately describe this action, and generated clients know what they receive when calling the endpoint. 모든 작업을 이러한 특성으로 표시하는 것이 좋습니다.As a recommendation, mark all actions with these attributes.

API 작업에서 반환해야 하는 HTTP 응답에 대한 지침은 RFC 7231 사양을 참조하세요.For guidelines on what HTTP responses your API actions should return, see the RFC 7231 specification.