springboot로 Rest api 만들기(4) Swagger API 문서 자동화

전체 소스코드

https://github.com/GHGHGHKO/Springboot/tree/main/pepega_chapter_4

GitHub - GHGHGHKO/Springboot: 블로그에 업로드 된 소스코드

​

이전 포스팅에는 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/

SpringBoot2로 Rest api 만들기(4) – Swagger API 문서 자동화

https://github.com/codej99/SpringRestApi

GitHub - codej99/SpringRestApi: SpringBoot2, SpringSecurity, JWT, Stateless Restful API