1,概念
Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。
2,使用swagger优势
支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。
3,接下来开始整合，使用springboot项目，有web框架支持即可
4,需要的依赖
使用2.9.2版本稍微稳定一些
<dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.9.2</version> </dependency> <!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.9.2</version> </dependency>
5,新建一个config包，再新建一个SwaggerTest类
package com.example.demo.config; import org.springframework.context.annotation.Configuration; import springfox.documentation.swagger2.annotations.EnableSwagger2; @Configuration //点进源码可以发现该注解等价于Component //开启swagger2 @EnableSwagger2 public class SwaggerTest { }
6，运行项目，并在浏览器中输入http://localhost:8080/swagger-ui.html,出现以下界面，项目就初始化好了
7,配置属于自己的文档
由于在Docket类下的所有参数都是使用默认的参数（点击Docket源码即可知），正如上图界面中的参数都是默认的，因此可以重写类里面的方法以及修改方法中的参数
package com.example.demo.config; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.core.env.Environment; import org.springframework.core.env.Profiles; 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; import java.util.ArrayList; @Configuration //点进源码可以发现该注解等价于Component //开启swagger2 @EnableSwagger2 public class SwaggerTest { @Bean public Docket docket(){ * DocumentationType.SWAGGER_2：点进Docket可以发现构造方法中需要一个参数， * 在点进这个参数类DocumentationType就能发现具体的参数了 */ return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()) //是否启动swagger，如果参数为false，那么浏览器则禁止访问swagger //.enable(true) .groupName("郑辉盛") //.select ** .build为一套模板 .select() //RequestHandlerSelectors:配置要扫描接口的方式， // basePackage：可以指定要扫描的包 // any:扫描全部 //none：不扫描 //withMethodAnnotation:扫描方法上的注解 .apis(RequestHandlerSelectors.basePackage("com.example.demo")) //过滤什么路径 //.paths(PathSelectors.ant("/demo/**")) .build(); } //配置swagger信息apiInfo private ApiInfo apiInfo(){ //作者信息 Contact contact = new Contact("郑辉盛","","1652724084@qq.com"); return new ApiInfo( "郑辉盛的swagger文档", //标题 "即使再小的帆也能远航", //描述 "1.0", //版本 "https://blog.csdn.net/zhenghuishengq", contact, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList()); } }
8，再次运行，可以得到自己所设置的参数的界面了，右上角出现的那个为组名，就是.groupName(“郑辉盛”)所设置的
9，如果想多个人同时开发，就可以设置多个组名，因此需要多个Docket对象，可以在上诉代码中加入
@Bean public Docket docket2(){ return new Docket(DocumentationType.SWAGGER_2).groupName("a"); } @Bean public Docket docket3(){ return new Docket(DocumentationType.SWAGGER_2).groupName("b"); } @Bean public Docket docket4(){ return new Docket(DocumentationType.SWAGGER_2).groupName("c"); } @Bean public Docket docket5(){ return new Docket(DocumentationType.SWAGGER_2).groupName("d"); }
10,再次测试，可以发现多出了几个模块
11，以自己的模块进行测试，新建一个pojo包，并再建一个实体类User
package com.example.demo.pojo; import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; //给生成的文档注释 @ApiModel("用户实体类") public class User { @ApiModelProperty("用户名") public String name; @ApiModelProperty("密码") public String password; public User(String name, String password) { this.name = name; this.password = password; } public User(){} }
13,直接运行,
在Models中可以发现实体类，以及生成的文档注释
再次点开hello-controller
14，接下来到了紧张有刺激的开发人员测试环节
点开/hello3这个接口，并点击try it out，最后执行
最终出现以下界面，说明接口测试成功，没问题！
15，总结
可以通过swagger给一些比较难理解的属性或者接口，增加注释信息
接口文档实时更新
可以在线测试
