📌Swagger

API 문서 자동화 라이브러리인 Swagger 에 대해서 알아보겠습니다.

스웨거(Swagger)는 개발자가 REST 웹 서비스를 설계, 빌드, 문서화, 소비하는 일을 도와주는 대형 도구 생태계의 지원을 받는 오픈 소스 소프트웨어 프레임워크이다. 대부분의 사용자들은 스웨거 UI 도구를 통해 스웨거를 식별하며 스웨거 툴셋에는 자동화된 문서화, 코드 생성, 테스트 케이스 생성 지원이 포함된다.

wikipedia 에 나와 있는 설명입니다. 말 그대로 API 에 대한 Operation 문서를 웹으로 제공해 주는 프레임워크 입니다.

📌Swagger 의 필요성

API가 개발되면 클라이언트가 활용할 수 있도록 인터페이스 정의서를 만들어야 합니다. Operation 의 종류와 수용할 수 있는 매개변수와 타입, 응답 데이터의 구조와 타입 등을 상세하게 제공해야 클라이언트가 효율적으로 활용할 수 있습니다. 그래서 이런 내용들이 포함된 문서를 만들고 배포해야 했습니다. 하지만 문서 배포 방식은 지속적인 관리가 어렵고, 이로인해 문서와 실제 API 간 불일치 문제가 자주 발생하였습니다.
이러한 문제를 해결하면서도 정확한 정보를 제공할 수 있게 고안된 라이브러리가 Swagger 입니다.

📌Swagger 의 장점

📍자동화된 문서화

Operation 만 추가하면 자동으로 Swagger에 적용됩니다.

📍개발자 간의 의사소통 향상

Operation 각각 설명을 추가할 수 있고, 응답, 요청 객체가 자동 설정되고, 커스텀할 수 있습니다.

📍일관성 있는 API 명세

자동으로 문서화 되기 때문에 코드 수정만으로도 일관성 있는 명세가 가능합니다.

📌Swagger 의 단점

📍초기 설정의 복잡성

📌Swagger 설정 방법

📍Dependency 추가

springdoc openapi starter maven 을 검색하여 의존성을 추가합니다.

implementation 'org.springdoc:springdoc-openapi-starter-webmvc-ui:2.6.0'

springfox 의 swagger 는 2020년 이후 업데이트가 없기 때문에 현재에도 활발히 업데이트가 이루어지는 springdoc 의 의존성을 추가합니다.
단순히 의존성 추가만으로도 swagger page 에 접속이 가능합니다.
http://localhost:13713/my-api/swagger-ui/index.html URI 를 브라우저에 입력해봅니다.

Swagger site 가 연결되고, 이전에 작성하였던 Operation 목록이 표출되는 것을 확인할 수 있습니다.

📍application.yml 설정 추가

application.yml 에 Swagger 관련한 주요 설정을 추가하겠습니다.

springdoc:
  api-docs:
    path: /api-docs
  default-consumes-media-type: application/json
  default-produces-media-type: application/json
  swagger-ui:
    path: /swagger-ui.html
    operations-sorter: alpha
    tags-sorter: alpha
    display-request-duration: true
    doc-expansion: none
    display-operation-id: true
    filter: true

🎈springdoc.api-docs.path

API 에 대한 정보를 Json type 으로 전달하는 api-docs 의 주소를 설정합니다. API 에 대한 모든 정보를 포함하기 때문에 다양한 기능 구현에 활용할 수 있습니다.

🎈default-consumes-media-type, default-produces-media-type

기본 응답 Operation 의 요청, 응답 타입을 설정합니다. 아무 설정이 없을 경우 default media type 을 참고합니다.

🎈swagger-ui.path

swagger 접속 주소를 설정합니다. 설정한 URI 입력 시 index page 로 redirect 됩니다.

🎈operations.sorter

operation을 정렬 순서를 설정합니다. alpha : 알파벳 순으로 정렬 와 method : HTTP method 순으로 정렬 를 제공합니다.

alpha

method (Delete -> Get -> Post -> Put)

🎈tags-sorter

tag 명을 정렬 합니다. default 는 Swagger-UI 에 의해 결정된 순서(읽혀진순서 인것 같네요) 이고 alpha 옵션으로 알파벳순으로 정렬합니다.

🎈display-request-duration

응답에 걸린 순서로 default 는 false 이며 true 설정시 API 요청에 걸린 시간이 표출됩니다.

🎈doc-expansion

tag 를 Operation이 열린상태로 조회할 것인가에 대한 옵션이고, default 는 list 로 tag만 열린 상태로 표출됩니다. 이외, full : operation 까지 열린상태로 표출, none : 전체 닫힌 상태로 표출 이 있습니다.

🎈display-operation-id

다음에 설정해볼 operation-id 의 표출여부 설정 옵션입니다. 기본적으로 해당 Method 명이 표출되지만 true 설정하고 @Operation에 operationId 속성을 추가하면 operation-id가 표출됩니다.

🎈filter

tag를 검색할수 있을 영역을 추가하는 옵션입니다. default 는 false 이고 ture 입력 시 filtering 을 할수 있는 영역이 Swagger page 상단에 추가됩니다.

🎈enable

Swagger 에 접속여부를 설정합니다. false 옵션 설정 시 접속이 불가합니다. profile 설정으로 prod 설정시에는 접속할 수 없게 설정합니다. default 는 true

---
spring:
  config:
    activate:
      on-profile: prod
springdoc:
  swagger-ui:
    enabled: false

📚참고

📕 Spring 설정 파일을 통한 Swagger 설정

application.yml 파일을 통한 다른 옵션 설정은 Link 를 확인하세요!

📙 상세 설계

상세한 설계는 다음 작성 글 참고~