#需求：项目完成后领导要求出一个后端的接口文档，文档要求：输入参数（请求参数），输出参数（响应参数）要清晰明了，即不管是输入参数还是输出参数都要有参数说明。然后输入输出参数要和实际保持一致。要的效果如下：

这是预计输入参数：

{
  "courseId": "string",
  "createTime": "2020-12-28T03:57:40.232Z",
  "delFlag": "string",
  "matchRate": 0,
  "recId": "string",
  "updateTime": "2020-12-28T03:57:40.232Z",
  "userId": "string"
}

这是实际输入参数（有些参数是不需要传的，这个在详细的接口文档中会有说明）：

{
  "courseId": "164165161",
  "matchRate": 0,
  "recId": "1614651561165615",
  "userId": "1616511651"
}

这是预计响应参数：

{
  "code": 0,
  "data": {
    "current": 0,
    "hitCount": true,
    "pages": 0,
    "records": [
      {
        "accountType": "string",
        "avatarUrl": "string",
        "createTime": "2020-12-28T03:51:42.782Z",
        "delFlag": true,
        "groupId": "string",
        "nickName": "string",
        "updateTime": "2020-12-28T03:51:42.782Z",
        "userId": "string"
      }
    ],
    "searchCount": true,
    "size": 0,
    "total": 0
  },
  "msg": "string"
}

这是实际响应参数：

{
  "code": 0,
  "data": {
    "records": [
      {
        "userId": "501608400",
        "nickName": "test IT网机构",
        "accountType": "3",
        "avatarUrl": "rain01223/7a62d196aa1247bc9d12c5aad5f30224.jpg",
        "createTime": "2020-12-23T06:25:27.000+0000",
        "updateTime": "2020-12-23T06:25:27.000+0000",
        "delFlag": false,
        "groupId": "501608466224"
      }
    ],
    "total": 1,
    "size": 10,
    "current": 1,
    "orders": [],
    "hitCount": false,
    "searchCount": true,
    "pages": 1
  },
  "msg": "执行成功"
}

所需要的工具：

1.swagger json。
2.docway

总共分三步：
第一步：swagger输入输出参数设置，让swagger能识别，使别人知道这个接口的输入输出参数的含义，格式。
第二步： docway将swagger上的响应参数复制到docway的响应参数上面去，使docway的效果和swagger一样。
第三步：将docway导出为pdf文档。

swagger 的使用就不赘述了，网上一搜一大把。这里要说的是要达到那个效果需要做什么。

第一步:

（1）.接口说明，说明这个接口的功能，参数说明等。

 @ApiOperation(value = "保存",notes = "userId 用户id"+
            "nickName 昵称,accountType 账号类型,avatarUrl 头像")

（2）.如果某个接口需要传一个对象好让别人知道你这个接口需要传哪些参数，传参的格式，类型等如下图1，就需要加上这个注解

图1：

{
  "accountType": "string",
  "avatarUrl": "string",
  "createTime": "2020-12-28T06:05:35.594Z",
  "delFlag": true,
  "groupId": "string",
  "nickName": "string",
  "updateTime": "2020-12-28T06:05:35.594Z",
  "userId": "string"
}

@ApiImplicitParams({ @ApiImplicitParam(name = "CourseUser")})

CourseUser为对象的类名

（3）.返回值设置：
需要在方法上将返回值写清楚如

那么响应参数里面的响应值就是这样

{
  "code": 0,
  "data": {
    "current": 0,
    "hitCount": true,
    "pages": 0,
    "records": [
      {
        "accountType": "string",
        "avatarUrl": "string",
        "createTime": "2020-12-28T06:13:37.380Z",
        "delFlag": true,
        "groupId": "string",
        "nickName": "string",
        "updateTime": "2020-12-28T06:13:37.380Z",
        "userId": "string"
      }
    ],
    "searchCount": true,
    "size": 0,
    "total": 0
  },
  "msg": "string"
}

最后将swagger导出为json即可！


将上述json复制保存为json文件。
swagger的说明完毕！

第二步：

在docway创建一个项目。

由于docway不能识别swagger的响应参数如下，所以需要将响应参数复制到docway上面去

{
  "code": 0,
  "data": {
    "current": 0,
    "hitCount": true,
    "pages": 0,
    "records": [
      {
        "accountType": "string",
        "avatarUrl": "string",
        "createTime": "2020-12-28T06:13:37.380Z",
        "delFlag": true,
        "groupId": "string",
        "nickName": "string",
        "updateTime": "2020-12-28T06:13:37.380Z",
        "userId": "string"
      }
    ],
    "searchCount": true,
    "size": 0,
    "total": 0
  },
  "msg": "string"
}

第二步中将上述响应参数复制进去。

docway上面的响应参数就和swagger的响应参数一样了，跟真实的响应参数也一样了。
将所有接口的响应参数复制好后即可开始导出项目了。

第三步：

点击右上角的更多功能->导出项目
点击之后另存为pdf即可大功告成！