전체 소스코드
https://github.com/GHGHGHKO/Springboot/tree/main/pepega_chapter_4
이전 포스팅에는 H2 Database를 활용하여
GET, POST 방식으로 데이터를 출력하고 도출하는 방법을 진행했었다.
이번 포스팅에는 프론트앤드 개발자가 편하게 참고할 수 있는 문서인
Swagger라는 것을 활용하여 API 문서 자동화를 진행해보려 한다.
시작
build.gradle에 swagger 라이브러리 추가
본 포스팅에서는 2.9.x 버전 말고 2.6.1 버전을 활용하려 한다.
implementation 'io.springfox:springfox-swagger2:2.6.1'
implementation 'io.springfox:springfox-swagger-ui:2.6.1'
SwaggerConfiguration 작성
com.example.pepega 하위의 config package 안에 SwaggerConfiguration 파일을 생성한다.
package com.example.pepega.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
@Bean
public Docket swaggerApi() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(swaggerInfo()).select()
.apis(RequestHandlerSelectors.basePackage("com.example.pepega.controller"))
// basePackage : controller 하단의 Controller 내용을 읽어
// mapping된 resource들을 문서화 시킴
.paths(PathSelectors.any())
.build()
.useDefaultResponseMessages(false); // 기본으로 세팅되는 200,401,403,404 메시지 표시 x
}
private ApiInfo swaggerInfo() {
return new ApiInfoBuilder().title("Spring API Documentation")
.description("앱 개발시 사용되는 서버 API에 대한 연동 문서입니다.")
.license("pepega").licenseUrl("https://blog.naver.com/gudrb963")
.version("1")
.build();
}
}
basePackage("com.example.pepega.controller")).paths(PathSelectors.any())
controller package 안의 Controller 내용을 읽어
mapping된 resource들을 문서화시킨다.
PathSelectors.ant("/v1/**")
위 명령어를 활용하 v1 이후의 내용들만 문서화 시킬 수 있다.
swaggerInfo를 세팅하면 설명과 작성자 정보를 노출시킬 수 있다.
UserController 수정
package com.example.pepega.controller.v1;
import com.example.pepega.entity.User;
import com.example.pepega.repo.UserJpaRepo;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import lombok.RequiredArgsConstructor;
import org.springframework.web.bind.annotation.*;
import java.util.List;
@Api(tags = {"1. User"}) // UserController를 대표하는 최상단 타이틀 영역에 표시될 값 세팅
@RequiredArgsConstructor // class 내부의 final 객체는 Constructor Injection 수행, @Autowired도 가능
@RestController // 결과를 JSON으로 도출
@RequestMapping(value = "/v1") // api resource를 버전별로 관리, /v1 을 모든 리소스 주소에 적용
public class UserController {
private final UserJpaRepo userJpaRepo;
@ApiOperation(value = "회원 조회", notes = "모든 회원을 조회한다.") // 각각의 resource에 제목과 설명 표시
@GetMapping(value = "/user") // user 테이블의 모든 정보를 읽어옴
public List<User> findAllUser() { // 데이터가 1개 이상일 수 있기에 List<User>로 선언
return userJpaRepo.findAll(); // JPA를 사용하면 CRUD에 대해 설정 없이 쿼리 사용 가능 (select * from user 와 같음)
}
@ApiOperation(value = "회원 입력", notes = "회원을 입력한다.")
@PostMapping(value = "/user") // user 테이블에 데이터를 입력하는 부분 insert into user (msrl, name, uid) values (null, ?, ?) 와 같음
public User save(@ApiParam(value = "회원아이디", required = true) @RequestParam String uid, // 파라미터의 설명을 보여주기 위해 세팅
@ApiParam(value = "회원이름", required = true) @RequestParam String name) {
User user = User.builder()
.uid(uid) // User 클래스에서 만들어진 변수 uid, name
.name(name)
.build();
return userJpaRepo.save(user);
}
}
@Api(tags = {"1. User"})
UserController를 대표하는 최상단 타이틀 영역에 표시될 값 세팅 (swagger 페이지에서)
@ApiOperation(value = "회원 조회", notes = "모든 회원을 조회한다.")
각각의 resource에 제목과 설명을 표시하기 위해 세팅
@ApiParam(value = "회원 이름", required = true) @ResponseParam ~~
파라미터에 대한 설명을 보여주기 위해 세팅
이제 서버를 실행한다.
http://localhost:8080/swagger-ui.html
위 링크에 접속하면
이렇게 페이지가 뜬다.
혹시라도 오류가 뜬다면 H2 Database가 켜져있는지 확인한다.
Try it out! 을 클릭하면 응답 결과도 확인 가능하다.
히맨도 입력됐다.
페페랑 히맨이 잘 들어와있다.
복잡한 프로젝트를 하다보면 API 를 전달해주는 문서가 햇갈린다.
swagger를 쓰면 번거롭게 문서작업을 추가로 하지 않아도 되고
즉시 테스트도 가능해서 작업이 한층 수월해진다.
출처
https://daddyprogrammer.org/post/313/swagger-api-doc/
https://github.com/codej99/SpringRestApi
'SpringBoot' 카테고리의 다른 글
springboot로 Rest api 만들기(6) ControllerAdvice를 이용한 Exception 처리 (0) | 2021.10.22 |
---|---|
springboot로 Rest api 만들기(5) API 인터페이스 및 결과 데이터 구조 설계 (0) | 2021.10.22 |
springboot로 Rest api 만들기(3) H2 Database 연동 (0) | 2021.10.21 |
springboot로 Rest api 만들기(2) HelloWorld (0) | 2021.10.21 |
SpringBoot로 Rest api 만들기(1) Intellij community, start.spring.io (0) | 2021.10.21 |