swagger는 여러 플랫폼을 API문서화 자동화를 지원하는 툴입니다.


준비과정

swagger를 사용하기위해 1번만 해주면 되는 준비과정입니다.

swagger설치

Install-Package Swashbuckle.AspNetCore

.net 에서 swagger을 사용하기위해서는 이 한줄이면 충분합니다.

Application 셋팅

namespace accountapi
{
    public class Startup
    {
        // This method gets called by the runtime. Use this method to add services to the container.
        public void ConfigureServices( IServiceCollection services )
        {
     
            services.AddMvc().SetCompatibilityVersion(CompatibilityVersion.Version_2_1);

            // Register the Swagger generator, defining 1 or more Swagger documents
            services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new Info { Title = "My API", Version = "v1" });

                var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
                var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
                c.IncludeXmlComments(xmlPath);
            });
        }

        // This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
        public void Configure( IApplicationBuilder app, IHostingEnvironment env )
        {
            app.UseStaticFiles();

            if ( env.IsDevelopment() )
            {
                using (var serviceScope = app.ApplicationServices.GetService<IServiceScopeFactory>().CreateScope())
                {
                }
                app.UseDeveloperExceptionPage();               
            }

            // Enable middleware to serve generated Swagger as a JSON endpoint.
            app.UseSwagger();

            // Enable middleware to serve swagger-ui (HTML, JS, CSS, etc.), 
            // specifying the Swagger JSON endpoint.
            app.UseSwaggerUI(c =>
            {
                c.SwaggerEndpoint("/swagger/v1/swagger.json", "My API V1");                
            });

            app.UseSession();
            app.UseMvc();
        }
    }
}


Project.csproj 수정

  <PropertyGroup>
    <TargetFramework>netcoreapp2.1</TargetFramework>
    <DockerTargetOS>Linux</DockerTargetOS>
    <!-- 추가하기 --!>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <NoWarn>$(NoWarn);1591</NoWarn>
  </PropertyGroup>

프로젝트에서 우클릭하여 .csproj를 수정합니다.


launchSetting.json 수정

.........
"accountapi": {
"commandName": "Project",
"launchBrowser": true,
"launchUrl": "swagger/",
"environmentVariables": {
"ASPNETCORE_ENVIRONMENT": "Development"
},
"applicationUrl": "http://localhost:5000"
},

개발환경에서 swagger 문서를 시작페이지로 시작하려면 위와같이 설정을 합니다. ( 옵션 )

http://localhost:5000/swagger/ 이 기본 경로입니다.

지속적 문서화와 테스트

API에 문서화기능 적용하기

/// <summary>
/// 로그인후 자신의 계정처리에 필요한 accessToken을 할당받습니다.
/// </summary>
/// <param name="user"></param>   
[HttpPost("login")]
public ActionResult<LoginRes> PostUser([FromBody] LoginReq user)
{    
    if (!ModelState.IsValid)
    {                
        return BadRequest(ModelState);
    }
    LoginRes result = new LoginRes();
    return Ok(result);    
}

위와같이 주석을 달게되면, API 에대한 추가적인 설명을 기입할수가 있습니다.

주석을 달지 않더라도 기본적으로 API문서화가 자동화가 됩니다. 


API Test하기

swagger의 핵심은, 단순하게 문서화가 아니라 API를 Test를 할수 있는 UI까지 제공해줍니다.


추가참고자료