Swagger는 REST API를 설계, 구축, 문서화 및 사용하는 데 도움이 되는 OpenAPI 사양을 기반으로 구축된 오픈 소스 도구 세트입니다.
https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-ui
Swagger는 두가지 버전의 라이브러리가 있는데
springfox-swagger, springdoc-openapi 두가지 중 요근래 많이 사용한다는 doc를 사용하겠다.
버전은 가장 최신버전 중 적당히 사용중인 버전으로 선택했다.
// https://mvnrepository.com/artifact/org.springdoc/springdoc-openapi-ui
implementation group: 'org.springdoc', name: 'springdoc-openapi-ui', version: '1.6.11'
public class SwaggerConfig {
@Bean
public GroupedOpenApi jwtApi() {
return GroupedOpenApi.builder()
.group("api") // 그룹설정
.pathsToMatch("/**")
.build();
}
@Bean
public OpenAPI customOpenAPI() {
SecurityRequirement securityRequirement = new SecurityRequirement().addList("Authorization");//JWT 전역 설정을 위해 추가
return new OpenAPI()
.addSecurityItem(securityRequirement)//JWT 전역 설정을 위해 추가
.components(new Components()
.addSecuritySchemes("Authorization",
new SecurityScheme().type(SecurityScheme.Type.HTTP).scheme("bearer").bearerFormat("JWT")))//JWT 전역 설정을 위해 추가
.info(new Info().title("Spring Boot API")
.description("API 예시입니다")
.version("0.0.1"));
}
}
중간에 보면 JWT 전역 설정을 위해 추가라는 부분이있는데 저 부분들을 추가 해주게되면 아래 사진과 같이
authorize 버튼이 생기며 전역 설정이 가능해진다
springdoc:
swagger-ui:
path: /swagger-ui.html
use-root-path: true
위의 세개 파일을 적용 시킨 후
http://localhost:8080/swagger-ui/index.html에 접속해보면 다음과 같은 화면을 볼 수 있다.
@Tag(name = "게시판", description = "게시판 API 입니다.")
@RestController
@RequiredArgsConstructor
public class BoardController {
private final BoardService boardService;
@Operation(summary = "게시글 추가 메서드", description = "게시글 추가 메서드 입니다.")
@PostMapping("/api/post") // 추가
public ResponseEntity<Object> addBoard(@RequestBody BoardRequestDto boardRequestDto, @AuthenticationPrincipal UserDetailsImpl userDetails){
return boardService.addBoard(boardRequestDto,userDetails.getUser());
}
@Operation(summary = "전체조회 메서드", description = "전체 조회 메서드 입니다.")
@GetMapping("api/posts") // 전체 조회
public List<BoardResponseDto> getBoard(){
return boardService.getBoard();
}
}
위의 @Tag와 @Operation을 적용시키면 아래와 같이 적용된다
그리고 아래와 같이 코드를 적용시키면 값에 설명을 달아줄 수 있다
@Parameter(name = "id", description = "글의 ID값")
@GetMapping("api/post/{id}") // 특정 글 조회
public BoardResponseDto getIdBoard(@PathVariable Long id){
return boardService.getIdBoard(id);
}
https://springdoc.org/#Introduction
https://hou27.tistory.com/entry/Spring-boot-Swagger%EB%A1%9C-API-%EB%AC%B8%EC%84%9C%ED%99%94%ED%95%98%EA%B8%B0
https://wildeveloperetrain.tistory.com/156