03、Swagger2和Springmvc整合详细记录（爬坑记录）

时间	内容	备注
2018年6月18日	基本使用	spirngmvc整合swagger2

开始之前这个系列博文基本是，在项目的使用中一些模块的内容记录，但是后期逐渐优化，不单单是整合内容。

swagger简介

1、swagger主要提供了三个功能:

• Swagger Editor: Swagger提供的一个编辑器，用来通过Swagger提供的特定的YAML语法来编写API文档
• Swagger Codegen: 代码生成器
• Swagger UI: YAML语法定义我们的RESTful API，然后它会自动生成一篇排版优美的API文档，并且提供实时预览。

spirngmv 整合swagger

其实这个整合例子甚多，可以选择的使用。

推荐：官方的说明文档，虽是英文但是各个配置含义说明的很清楚建议使用，后期的优化内容根据这个执行的。

导入基本步骤:

1、修改pom.xml；添加如下swagger的依赖

<!-- 构建Restful API -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.4.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.4.0</version>
</dependency>

2、添加如下的配置类
注意如下不是必要的步骤(swagger会使用默认配置)

package com.weir.utils;

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 org.springframework.web.servlet.config.annotation.WebMvcConfigurationSupport;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
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.weir")
class ApiConfig extends WebMvcConfigurationSupport {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.weir"))
                .paths(PathSelectors.any())
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("接口列表 v1.1.0") // 任意，请稍微规范点
                .description("接口测试") // 任意，请稍微规范点
                .termsOfServiceUrl("http://localhost:8080/swagger-ui.html") // 将“url”换成自己的ip:port
                .version("1.1.0")
                .build();
    }
}

3、修改springmvc.xml文件；添加关于swagger的配置，内容如下:

<mvc:default-servlet-handler />
<!-- 配置Swagger相关静态资源 -->
<mvc:resources location="classpath:/META-INF/resources/" mapping="swagger-ui.html"/>
<mvc:resources location="classpath:/META-INF/resources/webjars/" mapping="/webjars/**"/>
<!-- 添加扫描配置类 -->
<bean class="com.weir.utils.ApiConfig" />

4、代码中的使用：

@RequestMapping(value = "/login")
@ApiOperation(value = "用户登录", notes = "用户登录操作")
@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long")
@ResponseBody
public ServerResponse<User> login(String userName, String password, HttpSession session){

    ServerResponse<User> response = userService.login (userName, password);
    if (response.isSuccess ()){
        session.setAttribute ("user",response);
    }
    return response;
}

5、运行显示

导入遇到问题记录：

最重要的内容：（自己爬坑的内容）【一定要注意】

1、控制台报错内容：Getting HTTP 404 error on /swagger-ui.html but other swagger endpoint works

拦截路径改为/，不要配置成后缀的，例如：/*.do等，这会导致，wagger-ui.html页面被拦截，无法加载。

<!-- dispatcherServlet -->
<servlet>
<servlet-name>dispatcherServlet</servlet-name>
<servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
<init-param>
  <param-name>contextConfigLocation</param-name>
  <param-value>classpath:springmvc.xml</param-value>
</init-param>
</servlet>
<servlet-mapping>
<servlet-name>dispatcherServlet</servlet-name>
<url-pattern>/</url-pattern>
</servlet-mapping>

当然如果你要配置成带有后缀的也是可以的，请参考如下内容：
- 解决的关键参考页面 [github的issue]
- 关于配置成为的后缀的方式解决官方文档

总结：

• 他人博文只是具有参考意义，尽量参考官方说明文档，弄懂原理是关键
• 推荐官方文档，中文文档和博客参差不齐
• 不要位畏惧英文文档和资料