> For the complete documentation index, see [llms.txt](https://docs.sysout.co.kr/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sysout.co.kr/web/back-end/openapi-swagger/swagger-2.x-legacy.md).

# swagger 2.x (legacy)

## Springfox-swagger 2

이 문서에서는 Spring MVC Project에 swagger 2.x를 적용하는 과정에 대해서 다룬다.

## 프로젝트 생성

프로젝트는 Spring MVC Project로 생성한다. Spring STS 4에서 보이지 않을 경우 추가 플러그인 설치가 필요하다.

<div align="left"><img src="/files/Ow9N5adtFfKW2BBN7y3b" alt="Spring Legacy Project 선택"></div>

<div align="left"><img src="/files/b2jBMTK6zvHOoTT4mmmc" alt="Spring MVC Project를 선택한다"></div>

<div align="left"><img src="/files/BkpYmDb7uRFUhPMaUbP9" alt="top-level package를 설정한다."></div>

## pom.xml 설정

pom.xml에서 프로젝트를 설정한다.

* Java <mark style="color:red;">11</mark>
* Spring <mark style="color:red;">5.3.20</mark>
* 의존성 추가
  * com.faxterxml.jackson.core.jackson-databind <mark style="color:red;">(2.13.3)</mark>
  * io.springfox.springfox-swagger2 <mark style="color:red;">(2.9.2)</mark>
  * io.springfox.springfox-swagger-ui <mark style="color:red;">(2.9.2)</mark>

```markup
<?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
* 클래스 - ExampleController

```java
@RestController
public class ExampleController {
	
	@GetMapping("/")
	public String home() {
		return "home";
	}
	
	@GetMapping("/test")
	public String test() {
		return "test";
	}
	
}
```

## Swagger Configuration

Swagger Configuration을 추가하면 기본 설정이 완료된다. 설정을 추가하는 방법은 두 가지가 있다.

1. 기본 옵션 설정 사용 (Swagger2DocumentationConfiguration)
2. 커스텀 옵션 설정 사용 (직접 생성)

둘 다 <mark style="color:blue;">servlet-context.xml</mark>에 등록한다.

설정이 완료되면 다음 주소에서 프로젝트 분석 결과를 확인할 수 있다.

* {protocol}://{host}:{port}/{context-path}/v2/api-docs

### 기본 옵션 설정

{% code title="servlet.context.xml" %}

```markup
<beans:bean id="swagger2Config" class="springfox.documentation.swagger2.configuration.Swagger2DocumentationConfiguration"></beans:bean>
```

{% endcode %}

### 커스텀 옵션 설정

{% code title="servlet.context.xml" %}

```markup
<beans:bean id="swagger2Config" class="com.hacademy.swagger.configuration.SwaggerCustomConfiguration"></beans:bean>
```

{% endcode %}

* 패키지 - com.hacademy.swagger.configuration
* 클래스 - SwaggerCustomConfiguration

```java
@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 의존성을 열어서 확인할 수 있다.

<div align="left"><img src="/files/doj7uT7hjENfTSuh4EPm" alt="springfox-swagger-ui 의존성 내부 구조"></div>

이 중에서 swagger-ui.html은 자동 생성될 문서의 내용이며, webjars에 포함되어 있는 요소들은 자동 생성될 문서의 의존 라이브러리이다. 따라서 다음 요소들은 접근이 가능하도록 설정한다.

* swagger-ui.html
* /webjars/\*\*

{% code title="servlet.context.xml" %}

```markup
<resources location="classpath:/META-INF/resources/" mapping="swagger-ui.html"></resources>
<resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**"></resources>
```

{% endcode %}

설정을 마친 후 서버를 재시작하고 다음 주소로 접속한다.

* {protocol}://{host}:{port}/{context-path}/swagger-ui.html

다음과 같은 화면이 나오면 설정이 정상적으로 이루어진 것이다.

<div align="left"><img src="/files/PzaOxEigLckmNeh5Ncuz" alt=""></div>

{% hint style="info" %}
swagger 3는 2와 주소가 다르다

* swagger 2 - {protocol}://{host}:{port}/{context-path}/swagger-ui.html
* swagger 3 - {protocol}://{host}:{port}/{context-path}/swagger-ui/index.html

따라서 허용해야 하는 주소가 다르다.
{% endhint %}