Swagger在线API测试文档

Swagger API文档

• 前后端分离：

• 前端就负责展示数据，数据从哪来？后端提供的接口中得到

• 前端自己有一个叫伪造后端数据，json，这使得前端工程不需要后端仍可以跑起来

• 前后端的交互就是通过api

• 前后端相对独立，低耦合

• 前后端可以部署在不同的服务器上

好处：

之前有一个专门提供后端接口api的工具，postman（不推荐使用了）

1. 可以通过Swagger给一些比较难理解的属性和接口增加注释信息
2. 能在线实时测试后端提供的api，实时更新最新的api，降低集成的风险
3. 后端提供接口，需要实时更新最新的

Swagger：

Swagger是一个优秀的工具
【注意点】在正式发布项目的时候，记得关闭Swagger！！出于安全考虑。而且而且节省运行的内存

• 号称世界上最流行的Api框架
• RestFul Api 在线文档自动生成工具 => Api文档与Api定义自动同步
• 可以直接运行，可以在检测时Api接口
• 支持多种语言：java、php。。。
• 去看官网
• Swagger是老版的Swagger2是新版的

在项目中使用swagger 需要 springfox

• swagger2
• ui

SpringBoot集成Swagger

• 需要用到jackson，进行json解析和序列化

• 导入maven依赖

  <!-- 集成Swagger -->
  <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>2.9.2</version>
  </dependency>
  <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger-ui</artifactId>
      <version>2.9.2</version>
  </dependency>
  

• 编写一个工程

• 写配置

  1. 配置类：SwaggerConfig
     @Configuration
     @EnableSwagger2

  2. 他会进行默认配置，我们就可以访问
     swagger-ui.html

  3. 配置文件：

     package com.mao.config;
     
     import org.springframework.context.annotation.Bean;
     import org.springframework.context.annotation.Configuration;
     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
     @EnableSwagger2
     public class SwaggerConfig {
     
         //配置文档信息
         private ApiInfo apiInfo() {
             Contact contact = new Contact("毛毛", "https://www.cnblogs.com/maomao777/", "1227537114@qq.com");
             return new ApiInfo(
                     "毛毛的Swagger学习", // 标题
                     "学习演示如何配置Swagger", // 描述
                     "v1.0", // 版本
                     "组织链接", // 组织链接
                     contact, // 联系人信息
                     "Apach 2.0 许可", // 许可
                     "许可链接", // 许可连接
                     new ArrayList<>()// 扩展
             );
         }
         @Bean //配置docket以配置Swagger具体参数
         public Docket docket() {
             return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
         }
     }
     
     

• 一个Docket就是一个组group

• 想要实现在测试环境才可以访问swagger-ui界面，生产环境就不可以，
  可以使用@Value注解，或者是通过判断当前环境的端口号。。。

常用注解

Swagger注解	简单说明
@Api(tags = "xxx模块说明")	作用在模块类上
@ApiOperation("xxx接口说明")	作用在接口方法上
@ApiModel("xxxPOJO说明")	作用在模型类上：如VO、BO
@ApiModelProperty(value = "xxx属性说明",hidden = true)	作用在类方法和属性上，hidden设置为true可以隐藏该属性
@ApiParam("xxx参数说明")	作用在参数、方法和字段上，类似@ApiModelProperty

我们也可以给请求的接口配置一些注释

@ApiOperation("毛毛的接口")
@PostMapping("/mao")
@ResponseBody
public String mao(@ApiParam("这个名字会被返回")String username){
   return username;
}

@Value的用法 ！！！

在使用 @RequestMapping注解的时候，是Get就写@GetMapping注解，是Post就写@PostMapping注解

报错问题：

1. 集成swagger报错
   (2条消息) 解决 高版本SpringBoot整合Swagger 启动报错Failed to start bean ‘documentationPluginsBootstrapper‘ 问题_摸鱼佬的博客-CSDN博客
2. ErrorsHide
   Parser error on line 19end of the stream or a document separator is expected
   报错：原因：使用了Shiro权限设置，还没有登陆进行授权，所以访问不了，需要先登录