[Swagger] | Swagger

Swagger란?

Swagger는 OAS(Open Api Specification)를 위한 프레임워크이다.

개발자들이 필수 과제인 API 문서화를 쉽게 할 수 있도록 도와주며, 파라미터를 넣어서 실제로 어떤 응답이 오는지 테스트할 수 있다.

Swagger로 Api Path와 Request, Response 등을 한번에 알려줄 수 있어 프론트엔드 개발자와의 협업에도 유용하다.

Swagger 설정

1. 의존성을 추가한다.

2. SwaggerConfig 파일을 만들어서 Bean으로 등록해준다.

3. Controller에서 사용할 메소드에 @ApiOperation로 설명을 달아준다.(선택)

4. Swagger에 접속하여 잘 동작하는지 확인한다.

   • Swagger-UI 2.x
http://localhost[:8080]/{your-app-root}/swagger-ui.html
   • Swagger-UI 3.x
http://localhost[:8080]/{your-app-root}/swagger-ui/index.html

Swagger 의존성 추가

1. [Maven 프로젝트]

<!-- swagger를 위한 의존성 추가 -->
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-boot-starter -->
		<dependency>
			<groupId>io.springfox</groupId>
			<artifactId>springfox-boot-starter</artifactId>
			<version>3.0.0</version>
		</dependency>

2. [Gradle 프로젝트]

dependencies {
    ...
    implementation 'io.springfox:springfox-boot-starter:3.0.0'
    ...
}

Swagger 설정파일 생성 및 Bean 등록

[path가 한개일 경우]

// swagger 사용을 위해 선언한다.
@Configuration
@EnableSwagger3
public class SwaggerConfig {

	// Swagger를 위한 Docket 빈을 추가한다.

	@Bean
	public Docket api() {
		final ApiInfo apiInfo = new ApiInfoBuilder().title("도서관리 API")
				.description("<h3>RestApi에 대한 문서를 제공한다.</h3>")
				.contact(new Contact("User","https://velog.io/@test", "test@naver.com"))
                .version("1.0").build();

		return new Docket(DocumentationType.SWAGGER_2) // Swagger 2.0 기반의 문서 작성
				.apiInfo(apiInfo) // 문서에 대한 정보를 설정한다.
				.select() // ApiSelectorBuilder를 반환하며 상세한 설정 처리
				.apis(RequestHandlerSelectors.basePackage("com.test.book.controller"))// 대상으로하는 api 설정
				.paths(PathSelectors.any()) // controller에서 swagger를 지정할 대상 path 설정
				.build().useDefaultResponseMessages(false); // Docket 객체 생성
	}
}

[path가 여러개일 경우]

// swagger 사용을 위해 선언한다.
@Configuration
@EnableSwagger2
public class SwaggerConfig {

	// Swagger를 위한 Docket 빈을 추가한다.

	@Bean
	public Docket api1() {
		final ApiInfo apiInfo = new ApiInfoBuilder().title("도서관리 API")
				.description("<h3>RestApi에 대한 문서를 제공한다.</h3>")
				.contact(new Contact("Book", "https://velog.io/@test", "test@naver.com"))
				.version("1.0").build();

		return new Docket(DocumentationType.SWAGGER_2) // Swagger 2.0 기반의 문서 작성
				.groupName("1")
				.apiInfo(apiInfo) // 문서에 대한 정보를 설정한다.
				.select() // ApiSelectorBuilder를 반환하며 상세한 설정 처리
				.apis(RequestHandlerSelectors.basePackage("com.test.book.controller"))// 대상으로하는 api 설정
				.paths(PathSelectors.any()) // controller에서 swagger를 지정할 대상 path 설정
				.build().useDefaultResponseMessages(false); // Docket 객체 생성
	}
	
	@Bean
	public Docket api2() {
		final ApiInfo apiInfo = new ApiInfoBuilder().title("도서관리 API")
				.description("<h3>RestApi에 대한 문서를 제공한다.</h3>")
				.contact(new Contact("User", "https://velog.io/@test", "test@naver.com"))
				.version("1.0").build();

		return new Docket(DocumentationType.SWAGGER_2) // Swagger 2.0 기반의 문서 작성
				.groupName("2") // 그룹지정
				.apiInfo(apiInfo) // 문서에 대한 정보를 설정한다.
				.select() // ApiSelectorBuilder를 반환하며 상세한 설정 처리
				.apis(RequestHandlerSelectors.basePackage("com.test.user.controller"))// 대상으로하는 api 설정
				.paths(PathSelectors.any()) // controller에서 swagger를 지정할 대상 path 설정
				.build().useDefaultResponseMessages(false); // Docket 객체 생성
	}
	
}

• Docket: Swagger 설정의 핵심이 되는 Bean
• useDefaultResponseMessages: Swagger에서 제공해주는 기본 응답코드(200, 401, 403, 404), false로 설정하면 기본 응답코드를 노출하지 않는다.
• apis: api 스펙이 작성되어 있는 패키지(Controller)를 지정한다.
• paths: apis에 있는 API중 특정 path를 선택한다. 만약 .any로 설정하면 모든 path를 선택.
• apiInfo: Swagger UI로 노출할 정보

Api 설명 작성 - 컨트롤러

	@GetMapping("/books")
	@ApiOperation(value = "도서 목록을 반환한다.", response = Book.class)
	public ResponseEntity<?> list() {
		System.out.println("in");
		
		try {
			List<Book> books = service.select();
			if(books != null && !books.isEmpty()) {
				return new ResponseEntity<List<Book>>(books, HttpStatus.OK);
			}else {
				return new ResponseEntity<Void>(HttpStatus.NO_CONTENT);
			}
		} catch (SQLException e) {
			return exceptionHandling(e);
		}
	} 

• @Api: 해당 클래스가 Swagger 리소스라는 것을 명시한다.
• @ApiOperation: Api 메소드 수준에서 값 또는 태그 속성을 사용하여 작업을 설명한다.

Swagger 동작 테스트

[path가 하나일 경우]

[path가 2개일 경우]

• path가 여러개일경우 그룹을 선택하여 테스트를 진행할 수 있다.