SpringFox介绍

SpringFox 是一个开源的API Doc的框架， 它的前身是swagger-springmvc，可以将我们的Controller中的方法以文档的形式展现。 官方定义为： Automated JSON API documentation for API’s built with Spring。

Swagger介绍

Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。

SpringFox与Swagger

Swagger 是一种规范。
springfox-swagger 是基于 Spring 生态系统的该规范的实现。
springfox-swagger-ui 是对 swagger-ui 的封装，使得其可以使用 Spring 的服务。
Springfox其实是一个通过扫描代码提取代码中的信息，生成API文档的工具。API文档的格式不止Swagger的OpenAPI Specification，还有RAML，jsonapi，Springfox的目标同样包括支持这些格式。这就能解释那个swagger2的后缀了，这只是Springfox对Swagger的支持。

springBoot集成swagger

第一步：引入maven依赖，在你项目的pom文件中，引入下面依赖：

  1. <!--配置swagger3-->
  2. <dependency>
  3.   <groupId>io.springfox</groupId>
  4.   <artifactId>springfox-swagger-ui</artifactId>
  5.   <version>3.0.0</version>
  6. </dependency>

第二步：添加配置，添加swagger的配置类(非必需)

  2. /**
  3.  * Swagger3配置类
  4.  */
  5. @Configuration
  6. public class Swagger3Config {
  7.     @Bean
  8.     public Docket createRestApi() {
  9.         return new Docket(DocumentationType.OAS_30)
  10.                 .apiInfo(apiInfo())
  11.                 .select()
  12.                 .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
  13.                 .paths(PathSelectors.any())
  14.                 .build();
  16.     }
  17.     private ApiInfo apiInfo() {
  18.         return new ApiInfoBuilder()
  19.                 .title("Swagger3接口文档")
  20.                 .description("更多请咨询服务开发者XXX")
  21.                 // import springfox.documentation.service.Contact
  22.                 .contact(new Contact("作者", "作者地址", "作者邮箱"))
  23.                 .version("1.0")
  24.                 .termsOfServiceUrl("aaa")
  25.                 .build();
  27.     }
  28. }

第三步：在Application启动应用类上面加入@EnableOpenApi注解(实际测试非必需)

  1. @EnableOpenApi
  2. @SpringBootApplication
  3. public class AppServerApplication {
  5.     public static void main(String[] args) {
  6.         SpringApplication.run(AppServerApplication.class, args);
  7.     }
  9. }

第四步：在业务接口中添加swagger注解

  1. /**
  2.  * 用户实体类信息
  3.  * @author missye
  4.  * @since 2020/07/21
  5.  */
  6. @Data
  7. @NoArgsConstructor
  8. @AllArgsConstructor
  9. @ApiModel("用户基本信息")
  10. public class SysUser {
  12.     /**
  13.      * 用户名
  14.      */
  15.     @ApiModelProperty("用户名")
  16.     private String userName;
  17.     /**
  18.      * 用户昵称
  19.      */
  20.     @ApiModelProperty("用户昵称")
  21.     private String nickName;
  22.     /**
  23.      * 邮件
  24.      */
  25.     @ApiModelProperty("邮件")
  26.     private String email;
  27.     /**
  28.      * 手机号
  29.      */
  30.     @ApiModelProperty("手机号")
  31.     private String mobile;
  33. }
  36. @Api(value = "用户管理接口",tags = "用户信息接口类")
  37. @RestController
  38. @RequestMapping("sysUser")
  39. public class SysUserController {
  41.     @Autowired
  42.     private SysUserService sysUserService;
  43.     /**
  44.      * 查询
  45.      * @return
  46.      */
  47.     @ApiOperation("查询用户列表")
  48.     @GetMapping("/findUserList")
  49.     public List<SysUser> selectUserList(){
  50.         List<SysUser> userList = sysUserService.selectUserList();
  51.         return userList;
  52.     }
  54.     /**
  55.      * 分页查询
  56.      * @param pageNum 当前页数
  57.      * @param pageSize 每页的记录条数
  58.      * @return
  59.      */
  60.     @ApiOperation("分页查询用户列表")
  61.     @GetMapping("/findUserListByPage")
  62.     public PageInfo<SysUser> getUserBySearch(
  63.             @RequestParam("pageNum") int pageNum,
  64.             @RequestParam("pageSize") int pageSize) {
  65.         // TODO Auto-generated method stub
  66.         PageHelper.startPage(pageNum,pageSize);
  67.         List<SysUser> list= sysUserService.selectUserList();
  68.         PageInfo<SysUser> pageInfo = new PageInfo(list);
  69.         pageInfo.toString();
  70.         return pageInfo;
  71.     }
  73.     @GetMapping("/hello")
  74.     @ApiOperation(value = "返回请求信息", notes = "根据请求参数，返回请求信息")
  75.     @ApiImplicitParam(name = "name", value = "名字", defaultValue = "swagger")
  76.     public String hello(@RequestParam(value = "name", defaultValue = "swagger") String name) {
  77.         return "hello：" + name + "！";
  78.     }
  79. }

启动项目，访问swaggerui界面，注意，swagger3更新后，可访问ui界面路径与之前不同；

ip:port/context-path/swagger-ui/index.html

常用的swagger注解

  2. @Api：用在请求的类上，表示对类的说明
  4.   tags="说明该类的作用，可以在UI界面上看到的注解"
  6.   value="该参数没什么意义，在UI界面上也看到，所以不需要配置"
  8. @ApiOperation：用在请求的方法上，说明方法的用途、作用
  10.   value="说明方法的用途、作用"
  12.   notes="方法的备注说明"
  14. @ApiImplicitParams：用在请求的方法上，表示一组参数说明
  16.   @ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
  18.     name：参数名
  20.     value：参数的汉字说明、解释
  22.     required：参数是否必须传
  24.     paramType：参数放在哪个地方
  26.       · header --> 请求参数的获取：@RequestHeader
  28.       · query --> 请求参数的获取：@RequestParam
  30.       · path（用于restful接口）--> 请求参数的获取：@PathVariable
  32.       · body（不常用）
  34.       · form（不常用） 
  36.     dataType：参数类型，默认String，其它值dataType="Integer"   
  38.     defaultValue：参数的默认值
  40. @ApiResponses：用在请求的方法上，表示一组响应
  42.   @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
  44.     code：数字，例如400
  46.     message：信息，例如"请求参数没填好"
  48.     response：抛出异常的类
  50. @ApiModel：用于响应类上，表示一个返回响应数据的信息
  52.       （这种一般用在post创建的时候，使用@RequestBody这样的场景，
  54.       请求参数无法使用@ApiImplicitParam注解进行描述的时候）
  56. @ApiModelProperty：用在属性上，描述响应类的属性