H'academy
  • H'academy
  • Web
    • Back-end
      • Spring Framework
        • Spring 개발환경 구축
          • Project 생성
          • Maven 설정
          • Maven 저장소 위치 설정
          • Apache Tomcat 연동
          • Lombok 설정
        • Spring MVC Project
          • pom.xml
          • web.xml
          • root-context.xml
          • servlet-context.xml
          • DispatcherServlet
        • Controller
          • File Upload / Download
          • RestController(작성중)
        • Spring Test
          • Assert 단정문
          • Spring 환경 연동 테스트
          • MockMvc Test
        • Spring AOP
          • AOP 용어
          • Pointcut Expression
          • Filter
          • Interceptor
          • Filter vs Interceptor
          • Controller Advice(작성중)
        • Spring JDBC
          • DBCP
          • myBatis
            • ResultMap 활용
        • ETC
          • Logging
            • Tomcat Logging 설정
          • Property 관리
          • E-mail
            • Gmail 변경사항
          • Scheduler
          • Websocket
      • Spring Boot
        • STS 다운로드
        • 프로젝트 생성
        • 프로젝트 구조
        • Spring Devtools
        • Spring Controller
          • JSP 연동
            • * JSP 생성불가 문제
            • Spring Boot 3.x
          • Model
          • 요청 파라미터 처리
          • 경로 변수 처리
          • 요청 메소드
          • Redirect
          • Spring Actuator
        • Spring Boot JDBC
          • Database 정보
          • DAO Pattern
          • ORM Framework
            • myBatis
              • Mapper 생성
            • Spring Data JPA
        • Spring AOP
          • AspectJ
          • Filter
          • Interceptor
          • ControllerAdvice
        • REST API
        • Spring WebSocket
        • Send Mail
        • Logging
        • Spring Boot Test
        • Lombok
      • Java EE
        • 개발환경 구성
          • Server와 Client
          • Web Server와 WAS
        • Dynamic Web Project
      • Apache Tomcat
        • Apache Tomcat 구조
        • Tomcat User 생성
        • Tomcat Manager 설정
      • Maven
      • Jenkins
        • Installation
          • Github Webhook 설정
          • Maven 연동
        • Project setting
          • 소스 코드 관리 설정
          • 빌드 유발 설정
          • 빌드 작업 설정
      • OpenAPI(swagger)
        • swagger 2.x (legacy)
        • swagger 3.x (boot)
        • Swagger UI 꾸미기
        • SpringDoc
    • Front-end
      • HTML
        • Heading
        • <A>
        • <IMG>
        • <DIV>
        • <TABLE>
        • <FORM>
          • <INPUT>
          • <SELECT>
          • <TEXTAREA>
          • <FIELDSET>
        • List
      • CSS
        • CSS 적용 방식
          • 크기(size)
            • 픽셀(px)
          • 색상(color)
        • CSS 선택자
          • 스타일 우선순위
        • CSS 주요 속성
          • 크기 속성
            • border
            • margin
            • padding
            • box-sizing
          • 배경 속성
          • 글자 속성
            • font
            • text
          • 배치 속성
            • position
            • display
            • overflow
            • float
            • flexbox
        • CSS Reset
      • JS
        • syntax
          • let, const
          • 구조 분해 할당
          • spread operator
          • Object copy
          • this
          • module
        • jQuery
          • structure
          • function
          • ajax
            • ajax file upload
        • VueJS
          • CDN(Vue3)
            • 기본 구조
            • Vue Devtools
            • jQuery vs VueJS
            • Vue instance
              • data
                • IME issue
              • v-model
              • template
              • computed
              • watch
                • deep watch
                • vs Computed
              • methods
            • Vue directive
              • v-text
              • v-html
              • v-bind
                • v-bind style
                • v-bind class
              • v-on
                • once
                • prevent
              • v-show
              • v-if
              • v-for
          • Vue-cli 3
            • 프로젝트 구조
            • src
              • main.js
              • App.vue
              • HelloWorld.vue
            • Vue Router 4
              • History mode
              • 404 not found
              • Guard
                • beforeEach
            • Vuex
              • 이동 횟수 측정
            • axios
              • interceptor
          • Vue-electron
        • ReactJS
          • CDN(React18)
            • 템플릿 설명
            • JSX
            • render
            • Handling Events
              • onClick
              • onInput
            • Component
              • 클래스 컴포넌트
                • state
                • props
                • event
                  • Mouse
                  • Input
                • lifecycle
              • 함수형 컴포넌트
                • useState
                • useEffect
                • useReducer
                • useMemo
                • props
                • 조건부 렌더링
          • CRA
            • 자원 경로 설정
            • src 절대 경로 설정
            • react-router
            • Context API
            • Electron 설정
        • Webpack
          • NodeJS
          • Git
    • Ubuntu server
      • Jenkins
    • 테스트 도구
      • JMeter
        • Test Plan
        • Test Plan(with login)
        • Plugin 설치
    • WebRTC
  • Base Language
    • Java
      • Java 실행 과정
        • 개발 환경 구축
        • 샘플 코드 작성
        • 컴파일/실행
        • 환경 변수 설정
      • Java 초급
        • Hello world
        • 자료와 정보
        • 변수
          • 정수
            • 정수의 저장 원리
            • 정수형 변수 생성
          • 실수
            • 실수의 저장 원리
            • 실수형 변수 생성
          • 논리
            • 논리형 변수 생성
          • 문자
          • 문자열
            • 문자열 변수 생성
          • 사용자 정의 자료형
        • 연산자
          • 대입 연산
          • 부호 연산
          • 산술 연산
          • 복합 대입 연산
          • 증감 연산
          • 쉬프트 연산
          • 비트 연산
          • 비교 연산
          • 논리 연산
          • 삼항 연산
          • 변환 연산
        • 표준 입출력
          • 표준 출력
          • 표준 오류 출력
          • 표준 입력
            • Scanner 입력
        • 제어문
          • if 구문
            • 단일 조건
            • 두 가지의 조건
            • 여러 가지의 조건
          • switch~case 구문
          • while 구문
          • do~while 구문
          • for 구문
        • 랜덤(Random)
        • 배열
          • 1차원 배열
          • 2차원 배열
          • 다차원 배열
          • Sort
            • 선택 정렬
            • 버블 정렬
            • 삽입 정렬
      • Java 중급
        • 객체 지향 프로그래밍
        • 클래스
        • 인스턴스
        • 필드
        • 메소드
          • 설정(setter) 메소드
          • 반환(getter) 메소드
        • 생성자
        • 접근 제한
          • private
          • package
          • protected
          • public
        • 정적(static)
        • 불변(final)
        • 상수(constant)
        • 상속
          • this와 super의 이해
          • 멤버 변수 설정
          • 멤버 메소드 설정
          • 생성자 설정
        • 추상화
          • 추상 클래스
          • 인터페이스
        • 다형성
        • 중첩 클래스
          • 일반 중첩 클래스
          • static 중첩 클래스
          • 지역 중첩 클래스
          • 익명 중첩 클래스
      • Java API(작성중)
        • java.lang
        • java.util
        • java.text
        • java.time
        • java.io
        • java.net
        • java.sql
        • java.awt
        • javax.swing
      • Java 고급
        • 제네릭(Generic)
        • 열거형(Enum)
        • Annotation Type
          • Retention
          • Target
          • Nested Annotation
        • Java Reflection
          • Intro
          • Class
          • Field
          • Constructor
          • Method
          • Package
      • JDBC
        • 드라이버 로드
        • 연결 생성
          • JDBC Driver 유형
        • JdbcTemplate
      • Java 버전별 변경사항
        • Java 1.8
          • Lambda Expression
          • Stream API
          • java.time 패키지
        • Java 9
        • Java 12
          • switch~case
        • Java 13
          • Text Block
    • Arduino
      • 학습 준비
        • Reference
        • 아두이노 온라인 시뮬레이터
        • 전기의 이해
        • 그라운드(GND)의 이해
      • 개발 환경 구축
        • CH340 보드 설치
        • Editor 글꼴 설정
      • 아두이노 제어
        • 코드의 구성
        • 시리얼 출력
        • 디지털 출력
          • LED 출력
        • PWM 출력
        • 시리얼 입력
        • 디지털 입력
          • PIR 센서
        • 아날로그 입력
          • 온도 센서(LM35DZ)
          • 조도 센서
          • 가스 센서
        • 피에조 부저
        • 서보 모터 제어
          • 시리얼 서보 모터 제어
          • 스위치 서보 모터 제어
        • 온습도 센서(DHT-11)
        • LCD
      • 아두이노 통신
        • 블루투스(Bluetooth)
          • HC-06
            • 온도 센서 활용
          • HM-10
        • 와이파이(Wi-Fi)
          • ESP-01
            • WiFiEsp 라이브러리 추가
            • WiFiEsp 네트워크 스캔
        • 이더넷(Ethernet)
        • ArduinoJson 라이브리 사용
    • Regular Expression
  • Database
    • Oracle
      • 설치
        • SQL Plus
        • SQL Developer
        • DBeaver
        • Docker(Mac OS)
      • SQL
        • 관리자 명령
          • 사용자 관리
          • 권한 관리
          • Encoding 설정
          • 서비스 포트 설정
        • 사용자 명령
          • 테이블 관리
            • 테이블 항목 제약 조건
            • 외래키 제약조건
            • 데이터 유형
          • 시퀀스 관리
          • 데이터 관리
            • 데이터 추가
            • 데이터 조회
              • 오라클 내장 함수
              • 그룹 조회
              • Top N Query
            • 데이터 수정
            • 데이터 삭제
          • 뷰 관리
          • 인덱스 관리
          • 집합 연산
          • 테이블 조인
            • 등가 조인
            • 외부 조인
        • HR 계정
        • 기타 명령
          • 컬럼 간격 조정
      • 내보내기 및 불러오기
        • EXPDP, IMPDP
        • Docker로 실행중인 경우
      • 기타
        • 자동 세션 제거
        • Tablespace 관리
        • Unlock user
  • 면접대비
    • Q&A
      • Java
      • Database
      • Web
      • IT 일반상식
  • ETC
    • Eclipse IDE
      • 설치
      • 화면 설명
      • 환경 설정
      • 프로젝트 생성
      • 소스파일 작성 및 실행
    • Github
      • Github 계정 관리
      • Github 저장소 관리
        • Profile
        • Collaborators
        • Code
        • Issues
        • Pull requests
        • Action
          • Vue 3 Deploy Action
      • Personal Access Token
      • Git ignore 설정
        • Spring 개발용 샘플
      • Github Eclipse 연동
        • Branches
        • Project
        • Team project
          • Dynamic web project
          • Spring Boot Project
          • Branch 생성
          • Pull Request
          • Branch 보호
          • Branch 다시 생성
    • Figma
      • Team
      • Design
      • Component
    • 과정평가형
      • 실기 모의고사 1회
      • 실기 모의고사 2회
      • 실기 모의고사 3회
      • 실기 모의고사 4회
    • VScode
      • Live Server 실행 오류
      • Github 계정 변경
    • Naver ToastUI Editor
      • Editor 만들기
        • Editor options
          • File upload
      • Viewer 만들기
    • 문자 인코딩 방식
    • OBS
      • 녹화 잡음 제거 설정
    • Semantic Version
Powered by GitBook
On this page
  • SpringDoc
  • 의존성 추가
  • maven
  • gradle
  • Spring Boot 설정
  • 데모
  • 문서 정보 설정
  • 컨트롤러 명세 설정
  • 매핑 명세 설정
  1. Web
  2. Back-end
  3. OpenAPI(swagger)

SpringDoc

PreviousSwagger UI 꾸미기NextFront-end

Last updated 2 years ago

SpringDoc

springdoc-openapi는 Spring Boot 프로젝트의 문서를 자동으로 생성하는 자바 라이브러리이다. Swagger-UI를 기반으로 하며, application.properties 또는 application.yml을 통해 간단한 설정으로 사용이 가능하다는 장점이 있다.

의존성 추가

Maven Repository에서 springdoc 의존성을 찾아 pom.xml 또는 build.gradle에 추가한다.

작성 시점(2022-11-11) 기준 최신 버전은 1.16.12이다.

maven

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.12</version>
</dependency>

gradle

implementation group: 'org.springdoc', name: 'springdoc-openapi-ui', version: '1.6.12'

Spring Boot 설정

application.properties 또는 application.yml 파일에 다음과 같이 springdoc 설정을 작성한다.

# OAS(Open Api Service) setting
springdoc.swagger-ui.path=/swagger-ui.html
springdoc.packages-to-scan=com.hacademy.app.controller
  • springdoc.swagger-ui.path - swagger ui 접속 페이지 주소 (기본값 /swagger-ui/index.html)

  • springdoc.packages-to-scan - 문서화할 패키지 경로

설정에 대한 상세 정보는 다음 링크에서 확인할 수 있다.

실행하면 다음과 같은 페이지를 확인할 수 있다.

데모

공식 사이트에서 제공하는 데모 페이지는 다음 링크에서 확인할 수 있다.

문서 정보 설정

표시되는 문서의 정보를 설정하기 위해서 필요한 설정은 다음과 같다.

@OpenAPIDefinition(
	info = @Info(
		title = "API 제목",
		description = "API 상세 설명",
		version = "API 버전 정보"
	)
)
@Configuration
public class RestAPIConfiguration {

}

@Configuration을 생성하고 @OpenApiDefinition을 통해 문서의 정보를 설정한다. @Info에 설정하는 정보는 다음과 같다.

  • title - API 문서의 최상단 제목

  • description - 제목 아래 적힐 설명

  • version - 문서의 버전(통상적으로 v로 시작하며 major, minor, release 버전을 기재)

  • contact - 연락처 정보

  • license - 라이선스 정보

  • termsOfService - 이용 약관 정보

컨트롤러 명세 설정

컨트롤러 클래스의 표시 이름을 @Tag 설정으로 변경한다. 같은 태그는 같은그룹으로 표시된다.

@Tag(name = "포켓몬스터 컨트롤러")
@RestController
public class PocketMonsterController {

}

매핑 명세 설정

매핑에 대한 명세 설정은 @Operation설정으로 변경한다.

@Operation(
    summary = "포켓몬 상세",
    description = "포켓몬 상세",
    responses = {
        @ApiResponse(
            responseCode = "200", 
            content = @Content(
                mediaType = "application/json",
                array = @ArraySchema(
                    schema = @Schema(
                        implementation = PocketMonsterDto.class
                    )
                )
            )    
        ),
        @ApiResponse(
            responseCode = "404", 
            content = @Content(
                mediaType = "text/plain",
                schema = @Schema(implementation = String.class),
                examples = {
                    @ExampleObject(value="not found")
                }
            )
        ),
        @ApiResponse(
            responseCode = "500", 
            content = @Content(
                mediaType = "text/plain",
                schema = @Schema(implementation = String.class),
                examples = {
                    @ExampleObject(value="server error")
                }
            )
        )
    }
)
@GetMapping("/pocketmon/{no}")
public PocketMonsterDto find(
                @Parameter(description = "포켓몬 번호")
                @PathVariable int no) {
    return dao.find(no);
}
  • @Operation - 작업 설명

    • summary - 요약 설명

    • description - 상세 설명

    • responses - 응답 설정 (@ApiResponse)

      • responseCode - 응답 상태 코드

      • content - 응답 데이터 형태 (@Content)

        • mediaType - 응답 데이터 Content-Type

        • schema - 응답 객체의 형태(단일 객체인 경우) (@Schema)

        • arraySchema - 응답 객체 배열의 형태(배열 혹은 리스트인 경우) (@ArraySchema)

        • examples - 응답 객체 예시 (@ExampleObject)

  • @Parameter - 파라미터 설명

    • description - 설명

    • example - 응답 객체 예시 (@ExampleObject)

extensions - 확장 목록 ()

https://swagger.io/docs/specification/2-0/swagger-extensions/
OpenAPI 3 Library for spring-bootOpenAPI 3 Library for spring-boot
Logo
OpenAPI 3 Library for spring-bootOpenAPI 3 Library for spring-boot
Logo
Springdoc-openapi Properties
Logo
@Tag 적용 전
@Tag 적용 후