REST API 문서 만들기

학습 목표

1. springfox-swagger2 의존 설정 방법
2. springfox-swagger-ui 의존 설정 방법
3. Swagger 클래스 코드로 설정하기
4. springfox-swagger2 사용 방법 및 결과 확인 하기

 

 

Swagger는 두 가지 주요한 구성 요소로 구성되어 있습니다

1. Swagger Editor: 이는 사용자가 Swagger API 문서를 쉽게 작성하고 편집할 수 있는 UI를 제공합니다. 이 에디터는 YAML 또는 JSON 형식으로 Swagger 문서를 생성하고 검증합니다.
2. Swagger UI: 이는 Swagger로 작성된 API 문서를 사람이 읽을 수 있는 형태의 HTML 페이지로 변환합니다. 이를 통해 개발자들은 API가 어떻게 동작하는지 더욱 쉽게 이해할 수 있으며, 실제로 API를 테스트하고 쿼리를 수행할 수 있습니다.

 

 

 

 

의존성 xml

의존성 추가 

 

 

여기에 라이브러리들이 패키지처럼 들어가 있다.

 

https://mvnrepository.com/

 

 

 

 

 

 

 

 SpringFox Swagger2 Home » io.springfox » springfox-swagger2

SpringFox는 Java 기반의 프로젝트에서 Swagger를 쉽게 통합하고 사용할 수 있게 하는 라이브러리입니다. SpringFox는 Spring MVC, Spring Boot, Spring WebFlux 등의 Spring 프레임워크와 함께 사용되어 JSON 기반의 웹 서비스를 제공합니다.

SpringFox Swagger2는 이 라이브러리의 확장판 중 하나로, Swagger 2.x 사양을 따르는 API 문서를 자동으로 생성할 수 있게 해줍니다. 이 라이브러리는 코드에서 애노테이션을 읽어들여 API에 대한 메타데이터를 수집하고, 이 정보를 이용해 Swagger API 문서를 생성합니다.

 

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

 

 

 

 

config 패키지

package com.tenco.swagger.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;

@Configuration
public class SwaggerConfig {
	
	
	/**
	 * 설정 초기화 처리
	 * Swagger_2 라는 생성할 문서 유형 지정
	 * 특정 패키지 범위 내의 API를 문서화 대상으로 선택 가능
	 * 
	 */
	
	@Bean
	public Docket api() {
		return new Docket(DocumentationType.SWAGGER_2)
				.apiInfo(apiInfo())
				.select()
				.apis(RequestHandlerSelectors.basePackage("com.tenco.swagger"))
				.paths(PathSelectors.any())
				.build();
	}
	
	/**
	 * 
	 * ApiInfo 객체 준비 하기
	 * API 문서 정보를 설정하는 메서드
	 * title() API = 문서의 제목을 설정
	 * desc..() API = API의 문서에 대한 설정
	 * version() API = 문서의 버전을 설정
	 * 
	 */
	private ApiInfo apiInfo() {
		
		return new ApiInfoBuilder()
				.title("spring boot API TEST")
				.description("bank app 문서")
				.version("1.0.0")
				.build();
	
	}
}

 

<?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 https://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.7.10</version>
		<relativePath/> <!-- lookup parent from repository -->
	</parent>
	<groupId>com.tenco</groupId>
	<artifactId>swagger2</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<name>swagger</name>
	<description>Demo project for Spring Boot</description>
	<properties>
		<java.version>11</java.version>
	</properties>
	<dependencies>
		<!-- 의존성 추가 start -->
			<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
		<dependency>
		    <groupId>io.springfox</groupId>
		    <artifactId>springfox-swagger2</artifactId>
		    <version>2.9.2</version>
		</dependency>
		<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
		<dependency>
		    <groupId>io.springfox</groupId>
		    <artifactId>springfox-swagger-ui</artifactId>
		    <version>2.9.2</version>
		</dependency>
		<!-- 의존성 추가 end -->
		<!--<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-data-jpa</artifactId>
		</dependency>-->
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>

		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-devtools</artifactId>
			<scope>runtime</scope>
			<optional>true</optional>
		</dependency>
		<!--<dependency>
			<groupId>com.mysql</groupId>
			<artifactId>mysql-connector-j</artifactId>
			<scope>runtime</scope>
		</dependency>-->
		<dependency>
			<groupId>org.projectlombok</groupId>
			<artifactId>lombok</artifactId>
			<optional>true</optional>
		</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>
				<configuration>
					<excludes>
						<exclude>
							<groupId>org.projectlombok</groupId>
							<artifactId>lombok</artifactId>
						</exclude>
					</excludes>
				</configuration>
			</plugin>
		</plugins>
	</build>

</project>

 

package com.tenco.swagger.controller;

import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RestController;

import com.tenco.swagger.dto.MemberDto;

@RestController
public class RestApiController {

	@GetMapping("/api/getTest")
	private String getTest() {
		return "TEST1";
	}
	
	///api/getTest2?name="홍아"$email="a@naver.com"
	@GetMapping("/api/getTest2")
	private String getTest2(MemberDto memberDto) {
		return memberDto.toString();
	}
	
	@PostMapping("/api/postTest")
	public String postTest() {
		return "POST1";
	}
	
	@PutMapping("/api/putTest")
	public String putTest() {
		return "PUT1";
	}
	
	@DeleteMapping("/api/deleteTest")
	public String deleteTest(){
		return "DELETE1";
	}
	
}

 

 

package com.tenco.swagger.dto;

import io.swagger.annotations.ApiParam;
import lombok.Data;

@Data
public class MemberDto {

	@ApiParam(value = "사용자이름", required = true)
	private String name;
	@ApiParam(value = "사용자이메일", required = true)
	private String email;

}

 

 

 

package com.tenco.swagger.controller;

import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RestController;

import com.tenco.swagger.dto.MemberDto;

import io.swagger.annotations.ApiParam;

@RestController
public class RestApiController {

	@GetMapping("/api/getTest")
	private String getTest() {
		return "TEST1";
	}
	
	///api/getTest2?name="홍아"$email="a@naver.com"
	@GetMapping("/api/getTest2")
	private String getTest2(@ApiParam(value = "이름",required = true) String name) {
		return name.toString();
	}
	
	@PostMapping("/api/postTest")
	public String postTest() {
		return "POST1";
	}
	
	@PutMapping("/api/putTest")
	public String putTest() {
		return "PUT1";
	}
	
	@DeleteMapping("/api/deleteTest")
	public String deleteTest(){
		return "DELETE1";
	}
	
}