基於springMvc4集成Swagger

      本人在網上找了很多的關於SpringMvc整合的Swagger博客，但是按照操作或多或少出現一些問題，以下是本人SpringMVC真個好Swagger的具體步驟。

     我的整合分爲5個步驟，廢話不多少，現在開始進入正題。

1.pom.xml文件修改

        （1）導入swagger所需要的jar

        <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>

        （2）Jackson所需的jar包

        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-core</artifactId>
            <version>2.9.4</version>
        </dependency>

        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>2.9.4</version>
        </dependency>

        <!-- https://mvnrepository.com/artifact/com.fasterxml.jackson.core/jackson-annotations -->
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-annotations</artifactId>
            <version>2.9.4</version>
        </dependency>

2.Spring-mvc.xml文件修改

靜態文件：

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

攔截器過濾：

<mvc:exclude-mapping path="/swagger-ui.html"/>
<mvc:exclude-mapping path="/webjars/**"/>
<mvc:exclude-mapping path="/swagger-resources/**"/>
<mvc:exclude-mapping path="/v2/api-docs"/>

3.新建Swagger.java

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.EnableWebMvc;
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;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @Description TODO
 * @author：jeff
 * @date 2018/9/13 16:11
 * @Version 1.0
 */
@Configuration
@EnableSwagger2
@EnableWebMvc
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.a*.b*.controller"))//你的包
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("對外開放接口API文檔")
                .description("HTTP對外開放接口")
                .version("1.0.0")
                .termsOfServiceUrl("http://xxx.xxx.com")
                .license("LICENSE")
                .licenseUrl("http://xxx.xxx.com")
                .build();
    }
}

4.在Controller和實體增加註解

（1）controller增加註解

@Api()

用於類:表示標識這個類是swagger的資源

tags–表示說明

value–也是說明，可以使用tags替代

@ApiOperation() 用於方法:表示一個http請求的操作

value用於方法描述

notes用於提示內容

tags可以重新分組（視情況而用）

 

@ApiParam() 用於方法，參數，字段說明；表示對參數的添加元數據（說明或是否必填等）

name–參數名

value–參數說明

required–是否必填

@ApiOperation(value="登錄接口", notes="登錄接口")
@RequestMapping(value = "/test",method = {RequestMethod.POST})
@ResponseBody
public BaseResponse<String> test(@ApiParam(name = "userName",value = "用戶名",required = true)@RequestParam(value = "userName",required = true)String userName,
      @ApiParam(name = "passWord",value = "密碼",required = true)@RequestParam("passWord")String passWord,
      HttpServletRequest request, HttpServletResponse response){
   BaseResponse<String> resp = new BaseResponse<>();
   logger.info("用戶名："+userName+"  密碼:"+passWord);
   resp.setData("{'userName':"+userName+",'passWord':"+passWord+"}");
   return resp;
}

（2）請求的實體或返回的實體類

@ApiModel()用於類 :表示對類進行說明，用於參數用實體類接收

value–表示對象名

description–描述

都可省略

@ApiModelProperty()用於方法，字段: 表示對model屬性的說明或者數據操作更改

value–字段說明

name–重寫屬性名字

dataType–重寫屬性類型

required–是否必填

example–舉例說明

hidden–隱藏

例如：

@ApiModel(value = "用戶查詢返回信息")
public class UserInfoResp {
    @ApiModelProperty(value = "用戶名")
    private String userName;

    @ApiModelProperty(value = "性別")
    private String sex;
}

5.Swagger登錄地址

http://{ip}:{port}/{projectName}/swagger-ui.html

projectName爲你的項目名