프로젝트 설정
제 프로젝트의 설정은 다음과 같습니다. 아직 개발 중에 있어 의존성은 수시로 바뀌곤 합니다..ㅎ
- Project: Gradle project
- Language: Java
- Spring boot: 2.7.5
- Packaging: Jar
- Java: 11
- Dependencies: Spring web, Spring boot dev tools, Lombok, Spring Data JDBC, MyBatis Framework, MySQL Driver
build.gradle 추가 코드
먼저 다음과 같은 코드를 build.gradle에 추가합니다. 요즘은 springfox를 점차 안 사용하는 추세인거 같기도 하지만 저는 구글링했을때 springfox의 자료가 더 많아 springfox를 사용했습니다.
//Swagger2 gradle
implementation (group: 'io.springfox', name: 'springfox-swagger2', version: '2.9.2'){
exclude module: 'swagger-annotations' exclude module: 'swagger-models'
}
implementation "io.swagger:swagger-annotations:1.5.21"
implementation "io.swagger:swagger-models:1.5.21"
implementation group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.9.2'
Swagger API 자동 문서화
SwaggerConfig.java
@Configuration
@EnableSwagger2
@EnableAutoConfiguration
public class SwaggerConfig {
private final String version = "v1";
@Bean
public Docket commonApi() {
return new Docket(DocumentationType.SWAGGER_2)
.groupName(version)
.apiInfo(this.apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.story.example"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("제목")
.description("설명")
.version(version)
.build();
}
}
실행 후 http://localhost:8080/swagger-ui.html에 접속하면 다음과 같이 뜨는 걸 확인할 수 있습니다.
(제목, 설명이 저렇게 나타난다는걸 보여주기 위한 사진이기에 users는 없는게 맞습니다.)
에러
실행시 다음과 같은 오류가 발생 가능합니다.
Failed to instantiate [org.apache.ibatis.session.SqlSessionFactory]: Factory method 'sqlSessionFactory' threw exception...
해결 방법
: actuator 존재한다면 삭제 + application.properties에 해당 코드 추가
spring.mvc.pathmatch.matching-strategy = ANT_PATH_MATCHER
Api 작성
컨트롤러 작성시 다음처럼 애노테이션을 통해 api 내용을 작성할 수 있습니다.
설명을 위해 필요한 부분만 추출했습니다.
@Api(tags = "Users")
@RequestMapping("/users")
@RestController
public class UserController {
@ApiOperation(value = "회원가입", notes = "회원 id, 비밀번호, 닉네임을 입력해 user 정보를 생성한다.")
@PostMapping("/register")
public ResponseEntity<?> register(@RequestBody UserEntity user) {
userService.createUser(user);
return ResponseEntity.ok(HttpStatus.OK);
}
(...생략...)
}@Api
: 클래스를 Swagger 리소스 대상으로 표시합니다. tag를 작성하면 위에 사진의 Users처럼 해당 부분의 api 제목이 뜹니다.
@RequestMapping("/users")
: 저는 회원 관련 url을 모두 /users 로 시작하게 설계하여 이렇게 따로 뺐습니다. 따라서 이 부분은 필수적이진 않습니다.
@ApiOperation
: 요청 URL 에 매핑된 API 에 대한 설명입니다.
실행 결과
어플리케이션을 실행시키고 http://localhost:8080/swagger-ui.html 에 접속하면 다음같은 화면을 볼 수 있습니다.
포스팅 끝~
※ 급하게 공부하면서 개발중이라 틀린 내용이 있을 수 있습니다. 수정할 내용이 있으면 추후 수정하도록 하겠습니다.
참고 사이트
