| 时间 | 内容 | 备注 |
|---|---|---|
| 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]
- 关于配置成为的后缀的方式解决官方文档
总结：
- 他人博文只是具有参考意义，尽量参考官方说明文档，弄懂原理是关键
- 推荐官方文档，中文文档和博客参差不齐
- 不要位畏惧英文文档和资料
