如何将swagger导出为优雅的doc或者pdf⽂档
如何将swagger json导出为优雅的doc或者pdf⽂档
#需求：项⽬完成后领导要求出⼀个后端的接⼝⽂档，⽂档要求：输⼊参数（请求参数），输出参数（响应参数）要清晰明了，即不管是输⼊参数还是输出参数都要有参数说明。然后输⼊输出参数要和实际保持⼀致。要的效果如下：
这是预计输⼊参数：
{
"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
},
json值的类型有哪些
"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的响应参数⼀样了，跟真实的响应参数也⼀样了。将所有接⼝的响应参数复制好后即可开始导出项⽬了。
第三步：

版权声明：本站内容均来自互联网，仅供演示用，请勿用于商业和其他非法用途。如果侵犯了您的权益请与我们联系QQ:729038198，我们将在24小时内删除。