Springfox-swagger 2
이 문서에서는 Spring MVC Project에 swagger 2.x를 적용하는 과정에 대해서 다룬다.
프로젝트 생성
프로젝트는 Spring MVC Project로 생성한다. Spring STS 4에서 보이지 않을 경우 추가 플러그인 설치가 필요하다.
pom.xml 설정
pom.xml에서 프로젝트를 설정한다.
의존성 추가
com.faxterxml.jackson.core.jackson-databind (2.13.3)
io.springfox.springfox-swagger2 (2.9.2)
io.springfox.springfox-swagger-ui (2.9.2)
<?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/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>com.hacademy</groupId>
<artifactId>swagger</artifactId>
<name>spring-legacy-swagger</name>
<packaging>war</packaging>
<version>1.0.0-BUILD-SNAPSHOT</version>
<properties>
<java-version>11</java-version>
<org.springframework-version>5.3.20</org.springframework-version>
<org.aspectj-version>1.9.9.1</org.aspectj-version>
<org.slf4j-version>1.7.36</org.slf4j-version>
</properties>
<dependencies>
<!-- Spring -->
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-context</artifactId>
<version>${org.springframework-version}</version>
<exclusions>
<!-- Exclude Commons Logging in favor of SLF4j -->
<exclusion>
<groupId>commons-logging</groupId>
<artifactId>commons-logging</artifactId>
</exclusion>
</exclusions>
</dependency>
<dependency>
<groupId>org.springframework</groupId>
<artifactId>spring-webmvc</artifactId>
<version>${org.springframework-version}</version>
</dependency>
<!-- AspectJ -->
<dependency>
<groupId>org.aspectj</groupId>
<artifactId>aspectjrt</artifactId>
<version>${org.aspectj-version}</version>
</dependency>
<!-- Logging -->
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-api</artifactId>
<version>${org.slf4j-version}</version>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>jcl-over-slf4j</artifactId>
<version>${org.slf4j-version}</version>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>org.slf4j</groupId>
<artifactId>slf4j-log4j12</artifactId>
<version>${org.slf4j-version}</version>
<scope>runtime</scope>
</dependency>
<dependency>
<groupId>log4j</groupId>
<artifactId>log4j</artifactId>
<version>1.2.15</version>
<exclusions>
<exclusion>
<groupId>javax.mail</groupId>
<artifactId>mail</artifactId>
</exclusion>
<exclusion>
<groupId>javax.jms</groupId>
<artifactId>jms</artifactId>
</exclusion>
<exclusion>
<groupId>com.sun.jdmk</groupId>
<artifactId>jmxtools</artifactId>
</exclusion>
<exclusion>
<groupId>com.sun.jmx</groupId>
<artifactId>jmxri</artifactId>
</exclusion>
</exclusions>
<scope>runtime</scope>
</dependency>
<!-- @Inject -->
<dependency>
<groupId>javax.inject</groupId>
<artifactId>javax.inject</artifactId>
<version>1</version>
</dependency>
<!-- Servlet -->
<dependency>
<groupId>javax.servlet</groupId>
<artifactId>servlet-api</artifactId>
<version>2.5</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>javax.servlet.jsp</groupId>
<artifactId>jsp-api</artifactId>
<version>2.1</version>
<scope>provided</scope>
</dependency>
<dependency>
<groupId>javax.servlet</groupId>
<artifactId>jstl</artifactId>
<version>1.2</version>
</dependency>
<!-- Test -->
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>4.7</version>
<scope>test</scope>
</dependency>
<dependency>
<groupId>com.fasterxml.jackson.core</groupId>
<artifactId>jackson-databind</artifactId>
<version>2.13.3</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<artifactId>maven-eclipse-plugin</artifactId>
<version>2.9</version>
<configuration>
<additionalProjectnatures>
<projectnature>org.springframework.ide.eclipse.core.springnature</projectnature>
</additionalProjectnatures>
<additionalBuildcommands>
<buildcommand>org.springframework.ide.eclipse.core.springbuilder</buildcommand>
</additionalBuildcommands>
<downloadSources>true</downloadSources>
<downloadJavadocs>true</downloadJavadocs>
</configuration>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-compiler-plugin</artifactId>
<version>2.5.1</version>
<configuration>
<source>${java-version}</source>
<target>${java-version}</target>
<compilerArgument>-Xlint:all</compilerArgument>
<showWarnings>true</showWarnings>
<showDeprecation>true</showDeprecation>
</configuration>
</plugin>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>exec-maven-plugin</artifactId>
<version>1.2.1</version>
<configuration>
<mainClass>org.test.int1.Main</mainClass>
</configuration>
</plugin>
</plugins>
</build>
</project>
Controller 생성
테스트를 위한 @RestController를 생성한다.
패키지 - com.hacademy.swagger.controller
@RestController
public class ExampleController {
@GetMapping("/")
public String home() {
return "home";
}
@GetMapping("/test")
public String test() {
return "test";
}
}
Swagger Configuration
Swagger Configuration을 추가하면 기본 설정이 완료된다. 설정을 추가하는 방법은 두 가지가 있다.
기본 옵션 설정 사용 (Swagger2DocumentationConfiguration)
둘 다 servlet-context.xml에 등록한다.
설정이 완료되면 다음 주소에서 프로젝트 분석 결과를 확인할 수 있다.
{protocol}://{host}:{port}/{context-path}/v2/api-docs
기본 옵션 설정
<beans:bean id="swagger2Config" class="springfox.documentation.swagger2.configuration.Swagger2DocumentationConfiguration"></beans:bean>
커스텀 옵션 설정
<beans:bean id="swagger2Config" class="com.hacademy.swagger.configuration.SwaggerCustomConfiguration"></beans:bean>
패키지 - com.hacademy.swagger.configuration
클래스 - SwaggerCustomConfiguration
@EnableSwagger2
public class SwaggerCustomConfiguration {
@Bean
public Docket customApi() {
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
}
커스텀 클래스의 경우 추가 설정 없이 기본 설정으로만 작성하였다.
Swagger-UI 설정
swagger는 내부적으로 webjar를 사용하며, 자체 html 페이지를 가지고 있다. 이는 springfox-swagger-ui 의존성을 열어서 확인할 수 있다.
이 중에서 swagger-ui.html은 자동 생성될 문서의 내용이며, webjars에 포함되어 있는 요소들은 자동 생성될 문서의 의존 라이브러리이다. 따라서 다음 요소들은 접근이 가능하도록 설정한다.
<resources location="classpath:/META-INF/resources/" mapping="swagger-ui.html"></resources>
<resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**"></resources>
설정을 마친 후 서버를 재시작하고 다음 주소로 접속한다.
{protocol}://{host}:{port}/{context-path}/swagger-ui.html
다음과 같은 화면이 나오면 설정이 정상적으로 이루어진 것이다.
swagger 3는 2와 주소가 다르다
swagger 2 - {protocol}://{host}:{port}/{context-path}/swagger-ui.html
swagger 3 - {protocol}://{host}:{port}/{context-path}/swagger-ui/index.html
따라서 허용해야 하는 주소가 다르다.
