swagger 允许用户在一个html5 web 页面中，对API 进行文档化和交互 优点： 功能丰富 ：支持多种注解，自动生成接口文档界面，支持在界面测试API接口功能； 及时更新 ：开发过程中花一点写注释的时间，就可以及时的更新API文档，省心省力； 整合简单 ：通过添加pom依赖和简单配置，内嵌于应用中就可同时发布API接口文档界面，不需要部署独立服务。
实现 swagger 文档
添加依赖 主要是 添加 swagger2 核心包 以及 swagger-ui界面包 的依赖
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
配置 api 页面的基本信息
/**
* Created by Sean on 2018/10/10
*Api 文档页面 基本信息
* 可以通过注解注入相关配置。
* 通过这些配置可以指定在spring-boot启动时扫描哪些controller层的文件夹，
* 另外可以指定API文档页的标题和描述信息等内容
* @author Sean
*/
@Configuration
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.voicecyber"))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title(" RESTful APIs")
.description(" Rest Server api接口文档")
.version("1.0")
.build();
}
}
将swagger-ui 暴露到spring boot环境 主要是配置spring mvc 的一些资源拦截
/**
* Created by Sean on 2018/10/10
*将swagger-ui中的界面配置至spring-boot环境
* @author Sean
*/
@Component
public class WebMvcConfig extends WebMvcConfigurerAdapter {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("/js/**").addResourceLocations("classpath:/js/");
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
}
在controller 中编写自己的api 文档 主要在于参数，和接口的描述
@Api(value = "RestApi", description = "Rest Api Server")
@RestController
@RequestMapping("api")
public class RestApiController {
/**
*需要注意的是 必须指定 RequestMethod 的具体类型，不然前端会显示多种类型的Rest
*/
@ApiOperation(value = "信息总览", notes = "用户信息总览")
@ApiImplicitParam(name = "type", value = "获取信息的类型（name ,sex）", paramType = "query", dataType = "string")
@RequestMapping(value = "info", method = RequestMethod.GET)
@ResponseBody
public ResponseEntity getUserInfo(String type) {
System.out.println(type);
return new ResponseEntity("this is user info ", HttpStatus.OK);
}
}
.配置properties 文件 这个文件配置非常重要 ，主要在于 springfox.documentation.swagger.v2.host 的配置非常重要，在访问的swagger-ui.html 页面时。如果访问的路径不统一，那么可能会发生跨域的问题
springfox.documentation.swagger.v2.host=127.0.0.1:8080
springfox.documentation.swagger.v2.path=/api
server.port=8080
server.context-path=/rest
访问页面 使用上面的host 路径 再加上 swagger-ui.html 即可访问页面http://127.0.0.1:8080/swagger-ui.html github url：springbootrestswagger
