分别给属性加了类似这样的注解

小说:哪里有园林金盏菊种子?作者:丁安更新时间:2019-04-27字数:29950

队员:奥斯罗,武魂:鬼豹,三十六级敏攻系战魂师。魂环:两黄一紫。

你就想买最低价?大叶黄杨球的价格跌破成本了,还要怎么样低

剩下的能放心的似乎只有陆俊,陆俊的本事不用多说,前面已经介绍过,不仅易容术惊人,步法、暗器都是一流,就算经历了山谷那件事以后,林风还是有所怀疑,一个普通的世家,根本无法拥有这样的实力。
“不用了,你都已经要死的人了,还需要向上面要求什么支援啊”一道冷峻的声音在他的耳畔响起。

一想到当初在星斗大森林中唐三的实力,焱不禁有些颓然,“真不知道这家伙是怎么修炼的,比我们年纪还小,魂力却并不比我们低,最可怕的还是他那层出不穷的各种手段。算了,不说他,邪月,娜娜这次去,不会有危险吧?”

接口文档生成流程

介绍

目前我们QA在测试过程中, 存在着接口文档不全或有出入(包括更新)的情况。

这时候我们一般会阅读开发编写的代码或者直截了当去问开发。

这2种方法的弊端都很明显, 即增加了沟通和时间成本。

自己看代码且不论QA对于开发语言的熟悉程度, 有的代码QA并不可见。独自研究费时费力, 去找开发询问的时候,得问到对应的人, 他们还需要花费时间精力去搜寻。

==现在, 这些问题都将迎刃而解==。

原理介绍

通过swagger插件(如jar包)解析编写了接口注解的java代码, 而后通过生成的swagger.json文件解析出接口信息并导入接口文档管理工具(yapi)。

第一步: 编写注解

swagger是一个较为流行的接口文档管理工具, 但是这里我们不打算将他作为我们的大方向。其实接口文档的核心基本都已固定, 如path(route), 参数, 响应, 请求方式等。swagger在这点做得相当不错, 使用json-schema约束json字段的属性(required, example, type等)。

简而言之, 第一步就是通过注解对java中各个字段的参数做了约束, 通过插件生成json文档。

下面我们来看一个例子:

example地址, 这是一个长得像外国人的中国老哥

我们来看下注解的具体实现


package com.github.kongchen.swagger.sample.wordnik.resource;

import com.fasterxml.jackson.annotation.JsonProperty;
import io.swagger.annotations.*;
import com.github.kongchen.swagger.sample.wordnik.model.LoginData;

import javax.ws.rs.FormParam;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.Response;

@Path("/login")
@Api(value = "login", description = "登录接口")
@Produces({"application/json"})
public class woodyTest {
  @POST
  @ApiOperation(value = "用户登录")
  @ApiResponses(value = {@ApiResponse(code = 400, message = "Invalid ID supplied"),
          @ApiResponse(code = 404, message = "Order not found")})
  public Response getSuite(
          @ApiParam(value = "登录请求json参数", required = true) LoginData data) {
      System.out.println(data);
      return Response.ok().entity("").build();
  }
}

==图中的@POST, @ApiResponses, @Path等@==
意味都比较显著了吧, 因为我的java只有一点点语法基础, 所以理解可能有点出入, 我这里简单理解为注释的意思。如有不对求指教=。=

接下来我们来看看LoginData怎么写。


package com.github.kongchen.swagger.sample.wordnik.model;

import io.swagger.annotations.ApiModelProperty;

import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlRootElement;
import java.util.Date;

@XmlRootElement(name = "LoginData")  // 这是xml的信息, 我这里都去掉了不用
public class LoginData {
    @ApiModelProperty(value="用户名", name="user", example = "wuranxu")
    private String user;
     @ApiModelProperty(value="用户密码", name="pwd", example = "wodemimajiushimeiyoumima", required = true)
    private String pwd;

    @XmlElement(name = "user")
    public String getUser() {
        return user;
    }

    public void setUser(String user) {
        this.user = user;
    }

    @XmlElement(name = "pwd")
    public String getPwd() {
        return pwd;
    }

    public void setPwd(String pwd) {
        this.pwd = pwd;
    }
}

这个类里面, 有user和login属性, 分别给属性加了类似这样的注解

@ApiModelProperty(value="用户名", name="user", example = "wuranxu")

这里就是字段的约束。

第二步: 通过注解生成swagger.json

下载第一步那个小哥给出的demo, 解决好pom文件的依赖后。

在demo目录执行:

mvn clean compile

image.png

可以看到图中目录生成了swagger.json

image.png

来看看生成的json

image.png

第三步: 导入yapi

先来介绍下yapi吧~

yapi是去哪儿的大前端团队开发,基于react+antd的一套接口文档管理工具。给个掌声, 真的很良心。

具体地址

大家可以试用了感受一下。

至于不需要yapi, 钟爱原生swagger的童鞋, 也可以直接将swagger.json放入你的本地swaggerUI中查看接口文档啦。

那么附上一张swagger的截图吧...

image.png

后话

其实缺点就是开发需要在每个model的类加上注解, 写每一个接口也需要注解, 开发不好惹千万千万不要推:)

当然还有第四步啦, 因为···这些都是手动干的啊, 没人有那么多精力去手动维护这些破json。预知后事如何, 请看下集预告。(写文档码字太久要去干活儿了)

编辑:杜宗

发布:2019-04-27 00:00:00

当前文章:http://leetaemin.cn/content/2018-08/16/content_32171.html

0.3米高的龟甲冬青多少钱一棵? 重庆木槿价格便宜吗? 米径3公分大叶女贞什么价格能买到? 红刺梅批发价格多少钱一棵? 米迦勒月季可以爬藤吗? 紫藤与紫罗兰的区别有哪些? 花期长的藤本月季品种有哪些? 红三叶什么时候播种最好呢?

55657 63915 39681 53761 19403 16684 59166 10175 25594 48158 89792 17289 19500 75153 18494 63520 74555 42599 61839 19567

我要说两句: (0人参与)

发布