SpringBoot

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

pepega 2021. 10. 21. 16:27

전체 소스코드

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

 

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

블로그에 업로드 된 소스코드. Contribute to GHGHGHKO/Springboot development by creating an account on GitHub.

github.com

이전 포스팅에는 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 문서 자동화

앞서 개발한 api는 테스트를 위해 Postman을 따로 설치해야 하는 불편함이 있었습니다. 요번에 설명하려는 Swagger라는 문서 자동화 툴은 간단한 설정만으로도 테스트 가능한 Web UI를 지원하여 api를

daddyprogrammer.org

https://github.com/codej99/SpringRestApi

 

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

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

github.com