ASP.NET Core 6.0

Web API apps

Swagger / OpenAPI

Overview

OpenApi vs Swagger

OpenAPI는 스펙이다.

Swagger는 OpenAPI 스펙을 사용하는 툴이다.

OpenAPI 스펙

OpenAPI 스펙은 API의 사용할 수 있는 것들을 적어놓은 문서이다. json파일이다.

Swagger UI

Swagger UI는 생성된 OpenAPI 스펙을 사용하여, (웹)서비스에 대한 정보를 제공하는(provides) 웹기반 UI를 제공한다.(offers) Swashbuckle과 NSwag 둘 다 Swagger UI의 embedded version을 포함한다.

Get started with Swashbuckle

Swashbuckle 주요 구성요소

• Swashbuckle.AspNetCore.Swagger: a Swagger object와 미들웨어를 JSON endpoints의 SwaggerDocument object로 expose한다.
• Swashbuckle.AspNetCore.SwaggerGen: a Swagger generator는 routes, controllers, models에서 직접적으로SwaggerDocument objects를 빌드한다. 그것은 통상적을 Swagger JSON을 자동으로 노출하기 위해 Swagger endpoint middleware와 합쳐진다.
• Swashbuckle.AspNetCore.SwaggerUI: an embedded version of the Swagger UI tool.

추가하고 Swagger middleware 설정하기

Program.cs에서 서비스 컬랙션에 Swagger generator를 추가해라.(line 4)

1 builder.Services.AddControllers();
2 
3 builder.Services.AddEndpointsApiExplorer();
4 builder.Services.AddSwaggerGen();

생성된 JSON문서와 Swagger UI를 서빙하기 위한 미들웨어를 활성화해라.

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

앞서 코드는 오직 Development일 때만 Swagger middleware를 추가한다. UseSwaggerUI method call은 Static File Middleware를 활성화한다.

(web) app을 실행하고 https://localhost:<port>/swagger/v1/swagger.json을 열어봐라. endpoints를 설명하는 생성된 문서는 OpenAPI 스펙에서 표시된 것처럼 나타난다.

Swagger UI는 https://localhost:<port>/swagger에서 찾을 수 있다.

Swagger UI를 앱의 루트에 서비스하려면 RoutePrefix옵션을 사용할 수 있다.

app.UseSwaggerUI(options =>
{
    options.SwaggerEndpoint("/swagger/v1/swagger.json", "v1");
    options.RoutePrefix = string.Empty;
});

Customize and extend

XML 주석

활성화 하기

• Visual studio 솔루션 탐색기에서 프로젝트를 더블클릭(혹은 우클릭해서 편집)
• GenerateDocumentationFile를 true로 한다.

<PropertyGroup>
  <GenerateDocumentationFile>true</GenerateDocumentationFile>
  <NoWarn>$(NoWarn);1591</NoWarn>
</PropertyGroup>

xml 주석을 사용하도록 옵션을 추가한다.

builder.Services.AddSwaggerGen(options =>
{


    // using System.Reflection;
    var xmlFilename = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, xmlFilename));
});

3중 주석을 추가하면 Swagger UI에도 주석이 추가된다.

/// <summary>
/// Deletes a specific TodoItem.
/// </summary>
/// <param name="id"></param>
/// <returns></returns>
[HttpDelete("{id}")]
public async Task<IActionResult> Delete(long id)
{
    var item = await _context.TodoItems.FindAsync(id);

    if (item is null)
    {
        return NotFound();
    }

    _context.TodoItems.Remove(item);
    await _context.SaveChangesAsync();

    return NoContent();
}

json에도 summary가 추가된다.

"delete": {
    "tags": [
        "Todo"
    ],
    "summary": "Deletes a specific TodoItem.",
    "parameters": [
        {
            "name": "id",
            "in": "path",
            "description": "",
            "required": true,
            "schema": {
                "type": "integer",
                "format": "int64"
            }
        }
    ],
    "responses": {
        "200": {
            "description": "Success"
        }
    }
},

remarks를 추가해서 샘플을 넣을 수도 있다.

/// <summary>
/// Creates a TodoItem.
/// </summary>
/// <param name="item"></param>
/// <returns>A newly created TodoItem</returns>
/// <remarks>
/// Sample request:
///
///     POST /Todo
///     {
///        "id": 1,
///        "name": "Item #1",
///        "isComplete": true
///     }
///
/// </remarks>
/// <response code="201">Returns the newly created item</response>
/// <response code="400">If the item is null</response>
[HttpPost]
[ProducesResponseType(StatusCodes.Status201Created)]
[ProducesResponseType(StatusCodes.Status400BadRequest)]
public async Task<IActionResult> Create(TodoItem item)
{
    _context.TodoItems.Add(item);
    await _context.SaveChangesAsync();

    return CreatedAtAction(nameof(Get), new { id = item.Id }, item);
}