> For the complete documentation index, see [llms.txt](https://docs.sysout.co.kr/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sysout.co.kr/web/back-end/openapi-swagger/springdoc.md).

# SpringDoc

## SpringDoc

{% embed url="<https://springdoc.org/>" %}

**`springdoc-openapi`**&#xB294; Spring Boot 프로젝트의 문서를 자동으로 생성하는 자바 라이브러리이다. **Swagger-UI**를 기반으로 하며, <mark style="color:blue;">`application.properties`</mark> 또는 <mark style="color:blue;">`application.yml`</mark>을 통해 간단한 설정으로 사용이 가능하다는 장점이 있다.

<div align="left"><figure><img src="/files/gd4cZCXJG0AasLJOJosY" alt=""><figcaption></figcaption></figure></div>

## 의존성 추가

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

작성 시점(2022-11-11) 기준 최신 버전은 <mark style="color:red;">**1.16.12**</mark>이다.

### maven

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

### gradle

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

## Spring Boot 설정

<mark style="color:blue;">**`application.properties`**</mark> 또는 <mark style="color:blue;">**`application.yml`**</mark> 파일에 다음과 같이 springdoc 설정을 작성한다.

```properties
# 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 - 문서화할 패키지 경로

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

{% embed url="<https://springdoc.org/properties.html>" %}

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

<div align="left"><figure><img src="/files/knKmEZaheDRetFiPMVD5" alt=""><figcaption></figcaption></figure></div>

## 데모

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

{% embed url="<https://springdoc.org/#springdoc-applications-demos>" %}

## 문서 정보 설정

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

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

}
```

<mark style="color:red;">`@Configuration`</mark>을 생성하고 <mark style="color:red;">`@OpenApiDefinition`</mark>을 통해 문서의 정보를 설정한다. <mark style="color:red;">`@Info`</mark>에 설정하는 정보는 다음과 같다.

* title - API 문서의 최상단 제목
* description - 제목 아래 적힐 설명
* version - 문서의 버전(통상적으로 v로 시작하며 major, minor, release 버전을 기재)
* contact - 연락처 정보
* license - 라이선스 정보
* extensions - 확장 목록 (<https://swagger.io/docs/specification/2-0/swagger-extensions/>)
* termsOfService - 이용 약관 정보

## 컨트롤러 명세 설정

컨트롤러 클래스의 표시 이름을 <mark style="color:red;">`@Tag`</mark> 설정으로 변경한다. 같은 태그는 같은그룹으로 표시된다.

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

}
```

<div><figure><img src="/files/9KLlJV7axQllJRP227xB" alt=""><figcaption><p>@Tag 적용 전</p></figcaption></figure> <figure><img src="/files/WVTvIlQVjTtnzE8UcUty" alt=""><figcaption><p>@Tag 적용 후</p></figcaption></figure></div>

## 매핑 명세 설정&#x20;

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

```java
@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);
}
```

* <mark style="color:red;">**`@Operation`**</mark> - 작업 설명
  * summary - 요약 설명
  * description - 상세 설명
  * responses - 응답 설정 (<mark style="color:red;">**`@ApiResponse`**</mark>)
    * responseCode - 응답 상태 코드
    * content - 응답 데이터 형태 (<mark style="color:red;">**`@Content`**</mark>)
      * mediaType - 응답 데이터 Content-Type
      * schema - 응답 객체의 형태(단일 객체인 경우) (<mark style="color:red;">**`@Schema`**</mark>)
      * arraySchema - 응답 객체 배열의 형태(배열 혹은 리스트인 경우) (<mark style="color:red;">**`@ArraySchema`**</mark>)
      * examples - 응답 객체 예시 (<mark style="color:red;">**`@ExampleObject`**</mark>)
* <mark style="color:red;">**`@Parameter`**</mark> - 파라미터 설명
  * description - 설명&#x20;
  * example - 응답 객체 예시 (<mark style="color:red;">**`@ExampleObject`**</mark>)