> 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/swagger-ui-design.md).

# Swagger UI 꾸미기

## Swagger UI 꾸미기

이 문서에서는 설정된 Swagger UI에 정보를 추가하는 방법에 대해서 알아본다.

### 문서 정보

문서에 대한 기본 정보는 Swagger Configuration 파일에서 설정할 수 있다. Docket bean을 생성하는 부분에 다음과 같이 추가로 설정한다.

```java
.apiInfo(
	new ApiInfoBuilder()
		.title("문서의 제목")
		.description("문서의 설명")
		.version("문서의 버전")
		.license("라이선스 정보")
	.build()
)
```

### 컨트롤러 정보

컨트롤러 정보를 추가하고 싶을 경우 컨트롤러 위에 `Api`Annotation을 작성한다.

```java
@RestController
@RequestMapping("/sample")
@Api(tags = "샘플 REST API")
public class SampleController {

}
```

### 매핑 작업 설명

매핑에서 수행하는 작업에 대한 설명을 설정하고 싶을 경우 다음과 같이 `@ApiOperation` 을 사용한다.

```java
@ApiOperation(value = "샘플 매핑")
@GetMapping("/")
public String home(){
    return "home";
}
```

### 매핑 요청 파라미터 설명

매핑의 파라미터에 대해 설명을 설정하고 싶을 경우 다음과 같이 `@ApiImplicitParams`와 `@ApiImplicitParam`을 사용한다.

```java
@ApiImplicitParams({
    @ApiImplicitParam(name = "id", dataType = "String", value = "회원아이디", required = true),
    @ApiImplicitParam(name = "pw", dataType = "String", value = "회원비밀번호", required = true),
})
@PostMapping("/login")
public boolean login(@RequestParam String id, @RequestParam String pw){

}
```

### 매핑 응답 설명

매핑에 대한 응답 정보를 추가하고 싶을 경우 다음과 같이 `@ApiResponse` , `@ApiResponses` Annotation을 Mapping 상단에 추가한다.

```java
@ApiResponses(value = {
    @ApiResponse(code = 200, message = "로그인 성공"),
    @ApiResponse(code = 404, message = "일치하는 로그인 정보 없음"),
    @ApiResponse(code = 500, message = "데이터베이스 연결 오류")
})
@PostMapping("/login")
public boolean login(@RequestParam String id, @RequestParam String pw){

}
```

{% hint style="info" %}
Swagger에서 제공되는 기본 응답정보를 사용하고 싶지 않을 경우 Swagger Custom 설정파일의 Docket 생성 부분에 다음 작업을 추가해야한다.

```java
.useDefaultResponseMessages(false)
```

{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.sysout.co.kr/web/back-end/openapi-swagger/swagger-ui-design.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.