Swagger简介
1、认识Swagger
Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。
作用：
1. 接口的文档在线自动生成。
2. 功能测试。
Swagger是一组开源项目，其中主要要项目如下：
-
Swagger-tools:提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。
-
Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF...)、Servlets和Play框架进行集成。
-
Swagger-js: 用于JavaScript的Swagger实现。
-
Swagger-node-express: Swagger模块，用于node.js的Express web应用框架。
-
Swagger-ui：一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。
-
Swagger-codegen：一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码。
springboot整合Swagger
①添加依赖
<!-- swagger2借口测试-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.7.0</version>
</dependency>
<!-- swagger2-UI-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.7.0</version>
</dependency>
② 新建一个类配置Swagger
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;
/**
* Swagger2的接口配置
*
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig
{
/**
* 创建API
*/
@Bean
public Docket createRestApi()
{
return new Docket(DocumentationType.SWAGGER_2)
// 详细定制
.apiInfo(apiInfo())
.select()
// 指定当前包路径
.apis(RequestHandlerSelectors.basePackage("com.bettn"))
// 扫描所有 .apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
/**
* 添加摘要信息
*/
private ApiInfo apiInfo()
{
// 用ApiInfoBuilder进行定制
return new ApiInfoBuilder()
.title("标题：bettn系统接口文档")
.description("描述：用于测试接口")
.contact(new Contact("hzhh123", null, null))
.version("0.0.1")
.build();
}
}
③开启扫描包
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.ComponentScan;
@SpringBootApplication
@ComponentScan(basePackages={"com"}) //swagger扫描基类包
public class BettnAdminApplication {
public static void main(String[] args) {
SpringApplication.run(BettnAdminApplication.class, args);
}
}
④写一个类方便访问
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import io.swagger.annotations.Api;
@Api(value = "swagger访问页面",description = "swagger访问页面")
@Controller
public class SwaggerController{
@RequestMapping("/api/swagger")
public String toSwaggerUI(){
return "redirect:/swagger-ui.html";
}
}
Swagger的注解说明
@ApiParam(name=参数,value=参数说明,required=false|true)
注解写在参数的最左边，且参数需要使用@RequestBody、@RequestParam、@PathVariable参数修饰才起作用
@Api(value = 接口类标志,description = 接口类说明)
一般放在类上
@ApiOperation(value = 方法作用名,notes = 方法描述)
修饰方法，放在方法上
具体参考：https://blog.csdn.net/sanyaoxu_2/article/details/80555328
swagger-ui升级swagger-bootstrap-ui界面好看到起飞
如果项目已经集成了swagger，只需要在pom.xml添加，如果你的项目没有集成swagger，自行百度或看最下方的链接
swagger-bootstrap-ui是Swagger的前端UI实现,目的是替换Swagger默认的UI实现Swagger-UI,使文档更友好一点儿....
swagger-bootstrap-ui 只是Swagger的UI实现,并不是替换Swagger功能,所以后端模块依然是依赖Swagger的,需要配合Swagger的注解达到效果
添加依赖
<!--swagger-bootstrap-ui -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.3</version>
</dependency>
最终的依赖
<!-- swagger2借口测试-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagger.version}</version>
</dependency>
<!-- swagger2-UI-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger.version}</version>
</dependency>
<!--swagger-bootstrap-ui -->
<dependency>
<groupId>com.github.xiaoymin</groupId>
<artifactId>swagger-bootstrap-ui</artifactId>
<version>1.9.3</version>
</dependency>
访问
如 http://localhost:8080/doc.html
swagger-bootstrap-ui介绍
https://www.oschina.net/p/swagger-bootstrap-ui
码云：https://gitee.com/xiaoym/swagger-bootstrap-ui