Swagger2 프로젝트 설정

Swagger2 프로젝트 설정

2021. 8. 29. 00:55ㆍSpringBoot Swagger

프로젝트를 하다 보면 가장 귀찮은 일은 문서 작업일 것이다. API 개발 완료 후 FrontEnd 개발자에게 API 설명을 위해서는 IN/OUT 값을 정의한 명세서를 작성해야 할 것이다. 그리고 API가 변경될 때마다 현행화 해야 하는 일도 만만치 않은 작업일 것이다. 만약에 API 명세서를 현행화 하지 않는 다면 프로그램은 에러가 발생할 것이다.

Swagger를 사용하는 가장 큰 이유는 위에서 설명하였지만 별도의 문서 작업 없이 Documentation 작업이 가능하며 Postman을 대체해서 테스트도 가능하다는 점입니다.

어떤 분들은 단점으로 실제 코드보다는 주석의 양이 많아져서 가독성이 떨어진다 하지만 나중에 프로그램을 인수받는 입장에서는 코드도 중요하지만 코드에 대한 주석이 더 중요할 수 도 있을 것입니다.

예시를 통해 Swagger2의 사용방법을 알아보도록 하겠습니다.

프로젝트 설정

프로젝트 구조는 아래의 그림과 같습니다.

pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.4.1</version>
    </parent>

    <groupId>com.roopy</groupId>
    <artifactId>spring-boot-swagger</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <maven.compiler.source>9</maven.compiler.source>
        <maven.compiler.target>9</maven.compiler.target>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

</project>

AddressBookController.java

간단히 연락처를 등록하고, 조회 기능을 가진 Controller를 작성하도록 하겠습니다.

package com.roopy.controller;

import com.roopy.models.Contact;
import org.springframework.web.bind.annotation.*;

import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.ConcurrentHashMap;

@RestController
@RequestMapping("/api")
public class AddressBookController {

    ConcurrentHashMap<String, Contact> contacts =  new ConcurrentHashMap<>();

    @GetMapping("/{id}")
    public Contact getContact(@PathVariable String id) {
        return contacts.get(id);
    }

    @GetMapping("/")
    public List<Contact> getAllContacts() {
        return new ArrayList<Contact>(contacts.values());
    }

    @PostMapping("/")
    public Contact addContact(@RequestBody Contact contact) {
        contacts.put(contact.getId(), contact);
        return contact;
    }

}

Postman

작성된 프로그램의 테스트는 Postman을 통해서 테스트를 해보겠습니다.

01. 연락처 등록 결과

02. 전체 연락처 조회 결과

03. 특정 ID 조회 결과

여기까지 정상적으로 실행되었다면 기본적인 프로젝트 설정은 완료된 것입니다.

이제 Swagger2 설정부터 사용 방법에 대해 알아보도록 하겠다.

Swagger2 설정

01. spingfox-swagger2 dependency 추가

Swagger2를 사용하기 위해서 pom.xml에 swagger2 dependency를 추가해주어야 합니다.

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.9.2</version>
</dependency>

02. Swagger2 활성화

Swagger2 Dependency 추가 후 SpringbootSwaggerApplication.java 파일에서 @EnableSwagger2 어노테이션을 설정해주어야 합니다.

package com.roopy;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication
@EnableSwagger2
public class SpringbootSwaggerApplication {

    public static void main(String[] args) {
        SpringApplication.run(SpringbootSwaggerApplication.class, args);
    }

}

03. Swagger2 설정 확인

위의 과정까지 설정이 되었다면 서버 재시작 후 설정이 정상적으로 되었는지 확인합니다.

정상적으로 설정되었다면 서버 시작 시 아래와 같은 로그가 출력될 것입니다.

Mapped URL path [/v2/api-docs] onto method...

그리고 Postman에서 위의 URL /v2/api-docs를 호출하면 아래와 같이 보일 것입니다.

04. springfox-swagger-ui dependency 추가

위에서 json 형태로 API에 대한 명세를 확인할 수 있었지만 UI 상에서 확인을 위해서 ui depnency를 추가해줍니다.

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.9.2</version>
</dependency>

05. Swagger UI 확인

정상적으로 설정되었다면 아래와 같은 화면이 보일 것입니다.

메인화면이 정상적으로 보였다면 간단히 연락처 등록을 해보도록 하겠습니다.

첫 번째로 address-book-controller를 선택하면 아래와 같은 화면이 보일 것입니다.

위와 같은 화면이 보이면 두 번째 addContact 부분 아래 Try it out 버튼을 누르면 테스트 파라미터를 입력할 수 있도록 화면이 전환이 됩니다.

addContact의 메소의 파라미터를 보면 Contact 모델을 입력 파라미터로 받게 됩니다. 아래 화면을 보면 contact 부분에 모델에서 정의한 변수가 입력 파라미터로 보일 것입니다.

contact 부분에 테스트 파라미터를 추가해줍니다.

파라미터 등록 후 Execute 버튼을 누르면 아래와 같은 결과가 보일 것입니다.

위의 결과를 보면 Postman에서 테스트했던 거와 마찬가지로 정상적으로 등록된 것을 확인할 수 있습니다.

다음에는 좀 더 자세한 설정에 대해 알아보도록 하겠습니다.

예제는 아래 사이트에서 다운로드하실 수 있습니다.

https://github.com/roopy1210/spring-boot-swagger

GitHub - roopy1210/spring-boot-swagger

Contribute to roopy1210/spring-boot-swagger development by creating an account on GitHub.

github.com

위의 예제는 아래 강의 내용으로 작성되었습니다.

https://www.youtube.com/watch?v=gduKpLW_vdY

저작자표시 비영리

웹프로그램 이야기