SpringMVC + Swagger 2 통합 (spring box - swagger)

머리말
Swagger 는 RESTFUL 인터페이스 문서 온라인 자동 생 성 + 기능 테스트 를 위 한 도구 소프트웨어 입 니 다.Swagger 는 규범 적 이 고 완전한 프레임 워 크 로 RESTFul 스타일 을 생 성, 설명, 호출, 시각 적 으로 볼 수 있 는 웹 서비스 spring fox - swagger 는 Spring 로 API 를 구축 하 는 자동 JSON API 문 서 를 위 한 오픈 소스 도구 집합 으로 개발 자 들 이 swagger 를 프로젝트 에 신속하게 통합 할 수 있 습 니 다.또한 swagger 를 따로 배치 하지 않 으 면 spring fox - swagger - ui 를 사용 하여 프로젝트 에 통합 할 수 있 습 니 다.
2. 프로젝트 도입 의존
여기에서 우 리 는 Maven 을 사용 하여 프로젝트 관 리 를 진행 합 니 다.https://mvnrepository.com springfox - swagger 를 검색 하면 Springfox Swagger 2 와 Springfox Swagger Ui 를 볼 수 있 습 니 다. 최신 2.7.0 버 전 을 사용 하여 해당 하 는 pom. xml 설정 을 가 져 옵 니 다. 다음 과 같 습 니 다. : spring

    io.springfox
    springfox-swagger2
    2.7.0



    io.springfox
    springfox-swagger-ui
    2.7.0

시작 할 때 오류 가 발생 할 수 있 습 니 다. 알림 은 com. fasterxml. jackson. core. jackson - databind 를 찾 을 수 없습니다. 의존 도 를 추가 해 야 합 니 다.

       com.fasterxml.jackson.core
      jackson-databind
      2.6.6

배치
설정 부분 은 주로 두 부분 으로 나 뉘 는데 첫 번 째 는 Swagger 의 설정 입 니 다. 즉, 프로젝트 가 시 작 될 때 해당 하 는 설정 을 읽 어서 swagger 를 불 러 오고 문 서 를 스 캔 해 야 합 니 다. 또한 실행 환경 에 따라 swagger 스 캔 을 사용 할 지 여 부 를 결정 할 수 있 습 니 다.
1. swagger 설정

// WebAppConfig.java
package com.web.swagger2;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.ComponentScan;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;

import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
@EnableWebMvc
@ComponentScan(basePackages = {"com.web.api", "com.web.controller"}) //     
public class WebAppConfig {
    
    @Bean
    public Docket customDocket() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
    }
    
    /**
     *       
     * @return
     */
    private ApiInfo apiInfo() {
        Contact contact = new Contact("    ", "http://www.test.com", "[email protected]");
        return new ApiInfoBuilder()
            .contact(contact)
            .title("  API  ")
            .description("  API  ")
            .version("3.0.0")
            .build();
    }
}

2. spring 설정
두 곳 을 주의해 야 합 니 다. 먼저 / v2 / api - docs 의 경 로 를 지원 해 야 합 니 다. 차단 되면 정확 한 문서 json 으로 돌아 갈 수 없습니다.그 다음 에 프로젝트 에서 권한 통 제 를 하면 swagger 와 관련 된 경 로 를 놓 아야 합 니 다.

웹. xml 설정

    springServlet
    /*   //       /v2/api-docs  
  

spring - mvc. xml

설정

컨트롤 러 및 주해
컨트롤 러 (@ Controller) 는 스 캔 경로 (@ Component Scan) 에서 어떠한 설정 도 필요 하지 않 으 면 spring fox - swagger 에 의 해 인식 되 고 아래 의 예 는 간단 한 컨트롤 러 입 니 다.

@Controller
@RequestMapping("/test")
public class TestController {
    @ApiOperation(value="    API",notes = "     api")
    @ResponseBody
    @RequestMapping(value = "/hello",method = RequestMethod.GET)
    public String hello()
    {
        return "hello";
    }
}

주 해 는 참고 하 시기 바 랍 니 다.http://springfox.github.io/springfox/javadoc/current/다음은 주로 사용 하 는 주해 입 니 다.

@ ApiIgnore 는 주석 에 표 시 된 클래스 나 방법 을 무시 하고 API 문서 에 추가 하지 않 습 니 다

@ ApiOperation 각 API 기본 정보 보 여주 기

  value api  
  notes     

@ ApiImplicitParam 은 수신 매개 변수 유형, 이름, 필수 여부 등 정 보 를 규정 하 는 데 사 용 됩 니 다

name            
value     
required      boolean
paramType      body、path、query、header、form     
body   @RequestBody     POST  
path  url   {}   
query           ?query=q ,jquery ajax data       ，   {query:”q”},springMVC          
header   @RequestHeader    
form      ，     API  
dataType     ，        ，      ，   dataType = “java.util.Date”，springfox           

@ ApiImplicitParams 에는 @ ApiImplicitParam

이 여러 개 포함 되 어 있 습 니 다.

@ ApiModelproperty 는 모델 의 속성 에 대해 설명 을 추가 합 니 다. 예 를 들 어 위의 PageInfoBeen, BlogArticleBeen 등 두 가지 유형 에서 만 사용 할 수 있 고 클래스 에서 만 사용 할 수 있 습 니 다.

 value     
 required      boolean
 hidden      boolean 

@ Apiparam 은 클래스 나 controller 방법 에 사용 할 수 있 는 단독 매개 변 수 를 설명 합 니 다.주해 중의 속성 은 위 에 열거 한 동명 속성 작용 과 같다

5. 문서 보기
프로젝트 시작 후 접근 가능http://localhost:8080/v2/api- docs, 이 인 터 페 이 스 는 json 형식의 인터페이스 문서 정 보 를 되 돌려 줍 니 다.
방문 하 다.http://localhost:8080/swagger- ui. html 문서 보기
제 가 직접 사용 하 는 정식 프로젝트 의 배치 로 인해 여 기 는 캡 처 를 하지 않 고 여러분 이 직접 체험 할 수 있 습 니 다.
질문 과 건의 가 있 으 면 메 시 지 를 남 길 수 있 습 니 다.