springboot如何集成yapi

Swagger

介绍

在工作时，编写玩代码以后，我们还要写一个接口文档，提供给前端或者需要调用这个接口的人看，但是手写文档实在是太费事了，所以就出现了Swgger框架，可以实现调用restFul风格的web服务，自动生成接口文档，还可以在线测试接口 

使用步骤

原生的Swager被国人集成到了Spring Boot红中了，所以只需导入启动Swagger依赖

第一步：

<!-- swagger对springboot的集成 -->
<dependency>
  <groupId>com.spring4all</groupId>
  <artifactId>swagger-spring-boot-starter</artifactId>
<version>1.9.0.RELEASE</version>

第二步：
  在配置文件中配置wagger

server:
  port: 8080    #应用的端口号
  servlet:
    context-path: /swagger  #设置根路径为  swagger

#   Spring Boot   集成swagger配置
swagger:
  enabled: true  # 开启swagger
  base-package: com.itcast.swagger.controller   # 需要生成接口文档的类所在的包
  title: "测试工程"   # 文档标题
  description: "测试swagger  这是描述"    # 文档描述
  version: 1.0   # 文档的版本号

然后启动就行，这里也看到了有一个

base-package: com.itcast.swagger.controller # 需要生成接口文档的类所在的包

swagger就会去这个包中把里面的类生成文档。

运行结果：

注意事项 

@Controller：  swagger只会对标有@Controller注解或者他的派生类生成文档，也就是即使base-package扫描到了但是没有@Controller注解或者他的派生类依然生成不了文档

@RequestMapping：     swagger只会对有@RequestMapping生成文档

@RequestParam：这个注解接收的是例如  localhost:8080/stu?num=3      在swagger中这个名称是  问号传参     可视化界面为：query

@PathVariable: 这儿参数接受的是RestFul风格的请求，在swagger中叫 path请求   例如       localhost:8080/3     可视化界面为：path

@RequestBody：是接收的请求体中的请求  也叫 请求体传参    可视化界面为：body

 swagger注解开发

在我们上边的代码中，只能看到传参信息，但是并没有表示请求，但是我们可以通过swagger文档注解来说明文档的具体信息

常用注解：

@Api()用于类；
描述这个类是swagger的资源
@ApiOperation()用于方法；
描述一个http请求的操作
@ApiParam()用于方法，参数，字段说明；
描述参数的添加元数据（说明或是否必填等）
@ApiModel()用于类
表示对类进行说明，用于参数用实体类接收
@ApiModelProperty()用于方法，字段
表示对model属性的说明或者数据操作更改
@ApiIgnore()用于类，方法，方法参数
表示这个方法或者类被忽略
@ApiImplicitParam() 用于方法
表示单独的请求参数
@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam

代码示例

 如果把注解都弄到controller会有点不太舒服看着，因为既要加SpringMVC的注解又要加Swagger的，所以这时候就可以创建一个接口让Controller实现这个接口，然后在接口中把这些方法都添加swagger的注解说明，这样就完成了SpringMVC和swagger都区分开了

接口的代码

@Api(tags = "Hello Api 服务测试", description = "对Hello Api 服务提供接口")
public interface HelloApi {

    @ApiOperation("测试Hello方法")
    String hello();

    @ApiOperation("测试modifyStudentNum方法")
    @ApiImplicitParam(name = "numtest参数", value = "numtest参数解释", required = true, dataType = "string", paramType = "问号请求也叫query请求")
        //上边的required = true表示是否必须传的参数，true为必须
    Student modifyStudentNum(String numtest);

    @ApiOperation("测试mmodifyStudentName方法")
    @ApiImplicitParam(name = "name参数", value = "name参数解释", required = true, dataType = "string", paramType = "路径请求也叫path请求")
    Student modifyStudentName(String name);

    @ApiOperation("测试modifyStudent方法")
        //因为它传的是实体类所以要在实体类中添加注解
    Student modifyStudent(Student student);

    @ApiOperation("测试mofidyStudentBynNum综合方法")
    //因为这里参数很多所以需要使用@ApiImplicitParams({})  如果单个参数就是用@ApiImplicitParam()
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id参数", value = "id参数解释", required = true, dataType = "string", paramType = "路径请求也叫path请求"),
            @ApiImplicitParam(name = "name参数", value = "name参数解释", required = true, dataType = "string", paramType = "问号请求也叫query请求")
    })
    //因为它传的是实体类所以要在实体类中添加注解
    Student mofidyStudentBynNum(String id, String name, Student student);
}

 controller的代码

@RestController
@RequestMapping("stu")
public class HelloController implements HelloApi {
    /**
     * 测试无参数接口地址
       无参：get  http://ip:port/rootPath/stu/hello
     */
    @Override
    @GetMapping("hello")
    public String hello() {
        return "hello";
    }
    /**
     * 测试 queryString 风格的参入参数
       QueryString(问号传参)：
       get	http://ip:port/rootPath/stu?num=xxx
     */
    @Override
    @GetMapping
    public Student modifyStudentNum(@RequestParam("num") String numtest) {
        Student student = new Student(numtest, "xiaohong", 10, "parts");
        return student;
    }
    /**
     * 测试Restful风格的参入参数
       path(Restful):
       get	http://ip:port/rootPath/stu/xxxx
     */
    @Override
    @GetMapping("{name}")
    public Student modifyStudentName(@PathVariable("name") String name) {
        Student student = new Student("002", name, 10, "parts");
        return student;
    }
    /**
     * 测试json格式的传入参数
       请求体传参(json格式的数据):
       	post http://ip:port/rootPath/stu
       	requestBody：
        {
        	"xxxxx"："xxxx"
        }
     */
    @Override
    @PostMapping
    public Student modifyStudent(@RequestBody Student student) {
        student.setName("modifyName");
        return student;
    }
    /**
     * 测试 queryString 、Restful 和 json 格式的参数
       put	http://ip:port/rootPath/stu/xxxx?name=xxx
       	requestBody：
        {
        	"xxxxx"："xxxx"
        }
     */
    @Override
    @PutMapping("{id}")
    public Student mofidyStudentBynNum(@PathVariable("id") String id, @RequestParam("name") String name, @RequestBody Student student) {
        student.setName(name);
        student.setStuNo(id);
        return student;
    }
}

 实体类

@Data
@AllArgsConstructor
@ApiModel(value = "学员实体类  value",description = "对学员实体类进行描述  description")
public class Student {
    //学员编号
    @ApiModelProperty("学院编号")
    private String stuNo;
    //学成名称
    @ApiModelProperty("学院名称")
    private String name;
    //学员年龄
    @ApiModelProperty("学院年龄")
    private int age;
    //学员地址
    @ApiModelProperty("学院地址")
    private String address;

    //getter/setter 省略
}

 结果

 

Linux安装YApi 

 但是这个swapper需要代码运行起来才能使用，所以我们需要使用一个Yapi可以理解为将swapper中的接口文档持久化，当swapper打开以后将swapper的接口文档信息导入到YApi，这样即使swapper关闭了我们也是可以看到这个接口文档的通过YApi

 使用步骤：

拉取镜像：

docker pull registry.cn-hangzhou.aliyuncs.com/anoyi/yapi

 创建YApi的工作目录

 #创建目录
mkdir -p /usr/soft/yapi/config

 #进入到目录中 

cd /usr/soft/yapi/config

 YApi的配置文件config.json

{
  "port": "3000",
  "adminAccount": "[e-mail]",
  "timeout":120000,
  "db": {
    "servername": "mongo",
    "DATABASE": "yapi",
    "port": 27017,
    "user": "admin",
    "pass": "anoyi",
    "authSource": "admin"
  }
}

在 上边创建的 /usr/soft/yapi/config 中执行下面命令来初始化yapi的数据库索引及管理员账号

docker run -it --rm \
  --link mongo-yapi:mongo \
  --entrypoint npm \
  --workdir /yapi/vendors \
  -v $PWD/config.json:/yapi/config.json \
  registry.cn-hangzhou.aliyuncs.com/anoyi/yapi \
  run install-server 

初始化后yapi默认的账号为： [e-mail]    密码： ymfe.org

在 /usr/soft/yapi/config中执行下面命令来创建容器

docker run -d \
  --name yapi \
  --link mongo-yapi:mongo \
  --workdir /yapi/vendors \
  -p 3000:3000 \
  -v $PWD/config.json:/yapi/config.json \
  registry.cn-hangzhou.aliyuncs.com/anoyi/yapi \
  server/app.js

然后就可以访问游览器了，地址为   http://ip地址:3000 

游览器结果如下：

 

然后创建一个组再给组里创建一个项目，因为只有创建以后页面会变成下边这样

 

再进去swagger可视化界面进入下边这个地方

 

json

 下一步：

结果：