swagger는 여러 플랫폼을 API문서화 자동화를 지원하는 툴입니다.
준비과정
swagger를 사용하기위해 1번만 해주면 되는 준비과정입니다.
swagger설치
Install-Package Swashbuckle.AspNetCore
.net 에서 swagger을 사용하기위해서는 이 한줄이면 충분합니다.
Application 셋팅
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까지 제공해줍니다.
추가참고자료