이 글은 QWERTYU가 2019-4-12 14:24에 마지막으로 편집했습니다.
소개asp.net Core API 개발을 사용한 후에는 프로그래머에게 API 문서 작성이 고통스러운 작업일 수 있지만, 문서는 작성되어야 하며, 문서의 형식에 대한 구체적인 요구사항이 없다면 최종 문서는 전적으로 개발자의 기분에 달려 있습니다. 더 자세하거나 단순하게 할 수도 있습니다. 그렇다면 API 문서를 빠르고 효율적으로 만드는 방법이 있을까요? 답은 예입니다. Swagger는 가장 인기 있는 REST API 문서 생성 도구 중 하나입니다!
왜 REST API 문서 생성 도구로 Swagger를 사용하는가- Swagger는 개발자들이 API를 빠르게 배우고 실험할 수 있는 인터랙티브 API 콘솔을 생성할 수 있습니다.
- Swagger는 다양한 플랫폼에서 구현할 클라이언트용 SDK 코드를 생성할 수 있습니다.
- 스웨거 파일은 다양한 플랫폼에서 코드 주석을 통해 자동으로 생성할 수 있습니다.
- Swagger는 많은 훌륭한 기여자들과 함께 강력한 커뮤니티를 가지고 있습니다.
Swagger를 사용해 asp.net 코어에서 API 문서를 생성하는 방법은?- Swashbuckle.AspNetCore는 Core Web API ASP.NET Swagger 문서를 생성하는 오픈소스 프로젝트입니다.
- NSwag는 Swagger UI 또는 ReDoc을 ASP.NET 핵심 웹 API에 통합하는 또 다른 오픈소스 프로젝트입니다. API용 C# 및 TypeScript 클라이언트 코드를 생성할 수 있는 방법을 제공합니다.
다음은 Swashbuckle.AspNetCore의 예시입니다스워시버클의 구성 요소는 무엇인가요?- Swashbuckle.AspNetCore.Swagger: SwaggerDocument 객체를 Swagger 객체 모델이자 JSON 엔드포인트용 미들웨어로 노출합니다.
- Swashbuckle.AspNetCore.SwaggerGen: 경로, 컨트롤러, 모델에서 직접 SwaggerDocument 객체를 생성하는 Swagger 생성기입니다. 종종 Swagger 엔드포인트 미들웨어와 결합되어 Swagger JSON 파일을 자동으로 노출합니다.
- Swashbuckle.AspNetCore.SwaggerUI: Swagger UI 도구의 임베디드 버전입니다. Swagger JSON을 해석하여 웹 API의 기능을 설명하는 맞춤형 풍부한 경험을 구축합니다. 일반적인 방법에 대한 내장 테스트 도구가 포함되어 있습니다.
VS2017에 Swashbuckle을 어떻게 설치하나요?
첫 번째 방법: 패키지 관리자 콘솔 창에서 설치하세요
- 패키지 관리자 콘솔> 다른 Windows > 보기로 이동
- TodoApi.csproj 파일이 있는 디렉터리로 이동하세요
- 다음 명령을 실행해 주세요 · 설치-패키지 Swashbuckle.AspNetCore
-
두 번째 방법: NuGet 패키지 관리 대화상자에서:- 솔루션 탐색기에서 프로젝트를 우클릭> NuGet 패키지 관리하기를
- 패키지 소스를 nuget.org 로 설정하세요
- 검색창에 "Swashbuckle.AspNetCore"를 입력하세요
- 탐색 탭에서 Swashbuckle.AspNetCore 패키지를 선택하고 설치를 클릭하세요
-
Swagger 미들웨어 추가 및 구성먼저 네임스페이스를 소개합니다: Startup.ConfigureServices 메서드에서 서비스 컬렉션에 Swagger 생성기를 추가하세요: 에Startup.Configure메서드를 통해 생성된 JSON 문서와 Swagger UI를 제공하도록 미들웨어를 활성화합니다:
앱을 실행하고 그 앱으로 이동하세요https://localhost:<port>/swagger/v1/swagger.json。 엔드포인트를 설명하는 결과물인 문서는 다음과 같이 JSON 형식으로 표시됩니다.
이용 가능https://localhost:<port>/스웨거스웨거 UI를 찾아보세요. 아래 Swagger UI를 통해 API 문서를 탐색하세요.
근을 적용하려면 (http://localhost:<port>/Swagger UI를 제공하려면 다음 항목을 넣어 주세요.경로 접두사속성은 빈 문자열로 설정되어 있습니다:
스웨거의 고급 활용법 (커스터마이징 및 확장)Swagger를 사용해 API 문서에 설명 정보를 추가하세요AddSwaggerGen 메서드에서는 다음 구성 작업이 수행되며, 이 메서드는 저자, 라이선스, 설명 정보와 같은 정보를 추가합니다: 와거 UI 디스플레이 버전의 정보는 다음 그림에 나와 있습니다: 인터페이스 메서드에 주석 추가하기먼저 API를 클릭하고, 아래 그림처럼 펼쳐봅시다. 댓글이 없나요? 댓글을 어떻게 추가하나요? 아래 이미지에 보이는 3//으로 문서 주석을 추가하면, 아래 사진과 같습니다 그 다음 프로젝트를 실행하고 swaggerUI로 돌아가 댓글이 나타나는지 확인하세요 아직도 안 나타났어, 걱정 마, 아래를 봐! XML 주석 활성화XML 주석은 다음과 같은 방법으로 활성화할 수 있습니다: - 솔루션 탐색기에서 프로젝트를 우클릭한 후 속성(Properties)을 선택하세요
- 빌드 탭의 출력 섹션 아래 XML 문서 파일 박스를 보세요
-
XML 주석을 활성화하면 문서화되지 않은 공통 타입과 멤버에 대한 디버깅 정보를 제공합니다. 예를 들어, 경고 메시지가 많이 나타난다면, 다음 메시지는 경고 코드 1591 위반을 나타냅니다:
만약 강박장애가 있고 경고를 취소하고 싶다면요? 아래 이미지에 보이는 대로 취소할 수 있습니다
위에서 생성된 XML 문서 파일의 경로를 주목하세요.
메모: 1. 리눅스 또는 비윈도우 운영체제의 경우, 파일 이름과 경로는 대소문자 구분이 가능합니다. 예를 들어, "SwaggerDemo.xml" 파일은 Windows에서는 작동하지만 CentOS에서는 작동하지 않습니다. 2. 애플리케이션 경로를 얻으려면 AppContext.BaseDirectory를 사용하여 이를 얻는 것이 권장됩니다 프로젝트를 재구성해서 실행해서 댓글이 나타나는지 확인해 보세요 위 연산을 통해 요약할 수 있듯이, Swagger UI는 <summary> 위 주석 코드 요소들의 내부 텍스트를 API 대형 주석으로 표시합니다! 물론, 사용 방법 문서에 비평 요소를 추가할 수도 있습니다. 이 UI는 <summary> 요소에 명시된 정보를 보완하여 더 신뢰할 수 있는 Swagger UI를 제공할 수 있습니다. <remarks> 요소 콘텐츠는 텍스트, JSON 또는 XML을 포함할 수 있습니다. 코드는 다음과 같습니다: SwaggerUI를 사용해 API 인터페이스를 테스트해 보세요SwaggerUI를 통해 인터페이스 디버깅을 작은 예시로 살펴보겠습니다
- 테스트가 필요한 API 인터페이스를 클릭한 후, Parameters의 좌우에 있는 "Try it out" 버튼을 클릭하세요
- 다음 이미지에 보이는 매개변수 텍스트 박스에 매개변수를 입력하세요. 매개변수 2를 입력하세요
- 실행 버튼을 클릭하면 아래에 표시된 형식화된 응답이 나타나며, 아래 그림에 나타난 것입니다
자, 오늘은 Core WebApi에서 Swagger를 사용해 API 문서를 생성하는 방법에 관한 튜토리얼 ASP.NET 여기까지입니다. Swagger를 사용해 ASP.NET Core에서 API 문서를 생성하는 방법을 배우는 데 도움이 되길 바랍니다! 요약이 글은 API 문서를 손으로 작성하는 고충점부터 시작해, 자동으로 API 문서를 생성하는 도구인 Swagger로 이어집니다! 그 다음, 이해하기 쉬운 텍스트와 사진을 통해 SwaggerUI를 사용해 ASP.NET Core WebApi에서 API 문서를 생성하는 방법을 시연할 것입니다. 마지막으로, ASP.NET 코어에서 스웨거를 고급 활용법으로 소개하겠습니다! ASP.NET Core에서 스웨거를 사용하는 데 도움이 되길 바랍니다!
| 
게시됨 2019. 4. 12. 오후 2:14:46
|
|
|
|
