Swagger 란 무엇이며 사용 방법

Swagger 는 애플리케이션의 RESTful API 문서를 자동으로 구성하는 특수 도구입니다.

그 장점은 애플리케이션의 모든 엔드포인트를 살펴볼 수 있을 뿐만 아니라 요청을 보내고 응답을 수신하여 작동 중인 엔드포인트를 즉시 테스트할 수 있다는 사실에 있습니다.

Swagger 에 액세스하려면 게시된 애플리케이션에서 Preview 버튼을 누르고 필요한 게시 계획의 이름( Deploy Plan )을 클릭해야 합니다.

새로 열린 창에 사용 가능한 끝점 및 이러한 끝점과 연결된 메서드 목록이 표시됩니다. 일부 요청은 특정 그룹의 승인된 사용자에게만 제공됩니다( Endpoints 섹션에서 각 특정 요청에 대한 Auth module 의 Middleware 참조). 승인된 사용자에게만 허용되는 요청에는 Bearer Token 이 필요합니다.

Swagger 에서 해당 엔드포인트에 직접 액세스하여 이 토큰을 얻을 수 있습니다( Auth 섹션, POST /auth 요청).

Try it out 을 누르고 로그인과 암호를 입력하여 토큰을 얻으십시오.

Execute 에 요청이 전송됩니다. 성공적으로 진행되면 Bearer token 값이 있는 token 필드가 표시됩니다.

인증된 사용자 토큰을 얻는 두 번째 방법은 배포된 애플리케이션의 요청 본문에서 토큰을 찾을 수 있다는 것입니다.

1. 웹 브라우저에서 F12를 눌러 개발자 도구를 엽니다.
2. 배포된 애플리케이션에서 요청을 보냅니다(예: 테이블 업데이트). 이 요청을 보내는 사용자는 이 끝점에 액세스할 수 있는 권한이 있어야 합니다.
3. Network 탭을 열고 해당 요청을 찾습니다.
4. Headers 탭으로 이동하여 Request Headers 섹션을 찾으십시오. Bearer token 은 Authorization 아래에 표시됩니다.

Authorize 를 누르고 이전 단계에서 복사한 값을 붙여넣어 Bearer token 을 Swagger 에 제공하십시오.

테스트 요청을 위해 원하는 그룹과 실행할 방법을 선택하십시오. Try it out 을 누르고 요청 입력 매개변수를 입력합니다. Execute 을 클릭하여 응답을 실행합니다.

서버에서 요청을 올바르게 처리한 경우 가장 기대되는 응답은 코드 200이며 응답 구조가 어떻게 생겼는지 보여줍니다.

• 401 - 필요한 인증 토큰이 없거나 잘못되어 요청이 성공적으로 완료되지 않았습니다.

  

• 404 - 요청이 성공적으로 처리되었지만 요청된 리소스를 찾을 수 없습니다.

  

• 422 - 잘못된 매개변수가 요청 입력에 전달되었습니다.

  

• 500 - 서버에서 요청을 처리하는 동안 오류가 발생했습니다.

  

사용자 정의 오류 발생

사용자 지정 BP 및 관련 요청의 경우 BP 편집기에서 Raise Error 블록을 사용하여 설명과 함께 사용자 지정 오류 코드를 생성할 수 있습니다. 이러한 프로세스의 예는 다음과 같습니다.

이 경우 위의 BP와 연결된 엔드포인트에 대한 요청이 실패하면 서버는 DB: Create Candidate block 을 실행할 때 오류 텍스트가 포함된 418 오류를 발행합니다. 이 예에서 오류 코드는 사용자가 지정하는 모든 것일 수 있습니다.

참고: HTTP 418 I'm a teapot client 오류 응답 코드는 서버가 영구적으로 찻주전자이기 때문에 커피 추출을 거부했음을 나타냅니다. 일시적으로 커피가 없는 결합된 커피/티 포트는 대신 503을 반환해야 합니다. 이 오류는 1998년과 2014년에 만우절 농담에 정의된 Hyper Text Coffee Pot Control Protocol 에 대한 참조입니다.