Swagger+YApi

最新推荐文章于 2024-08-26 21:38:55 发布

原创最新推荐文章于 2024-08-26 21:38:55 发布 · 1.7k 阅读

6 ·

CC 4.0 BY-SA版权

文章标签：

#java #开发语言

笔记专栏收录该内容

56 篇文章

订阅专栏

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": "admin@anoyi.com",
"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默认的账号为： admin@anoyi.com 密码： 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

游览器结果如下：