SpringBoot中使用Swagger生成RESTful规范API文档

最新推荐文章于 2024-04-29 17:03:38 发布

permanent_2008

最新推荐文章于 2024-04-29 17:03:38 发布

阅读量345

点赞数

分类专栏： java开发 spring cloud

java开发同时被 2 个专栏收录

7 篇文章 0 订阅

订阅专栏

spring cloud

7 篇文章 0 订阅

订阅专栏

Swagger为我们提供了非常多的工具，其中最强的还要算这个代码的生成工具。在前后端分离的大环境下，前后端之间订立的接口显得尤为重要，接口在订立之后变动的可能性已经很小，这就要求我们提前去设计接口，也就是我们为前端提供的API。

但是我们发现，在开发过程中订立的接口寿命其实很短，这是一件非常严重的事情。因此Swagger为我们提供了另外一种比较优雅的方式：就是你先订立接口，然后再去生成接口；也就是使用接口文档去生成代码，这是非常好的一种实践方式。

Mock Server为我们解决下面的问题：
1、我们设计了API，但后台还没有开发完成；
2、因为网络等原因，导致直接调用真实的后台API会很不稳定或者很耗时。

前期准备
先看下面文章，如何生成API文档，拿到文档后，我们才能生成Mock Server Code
SpringBoot中使用Swagger生成RESTful规范API文档
http://blog.csdn.net/a78270528/article/details/78506338

实现步骤：
1、访问：http://localhost:8090/v2/api-docs，会返回接口的JSON数据，复制（文章最后有完整JSON代码）。

2、再打开Swagger Editor（https://editor.swagger.io），也可以下载代码，在本地部署访问。我们这里使用在线方式，粘贴刚刚复制的JSON，提示转成YAML：

3、点击Generate Server，选择spring，直接弹出下载代码。

4、解压后，就是一个完整的Spring Boot工程，Import（Projects from Folder or Achive）到我们的MyEclipse：

5、这时候我们可以正常启动项目，Swagger2SpringBoot，右键Run as..

6、这里面推荐一个工具Postman，最好使用Chrome下的插件方式安装，单独的Postman不支持中文。在Postman中访问我们之前编写的接口：

7、我们按照接口要求填写了接口，发送后返回HTTP请求415错误 – 不支持的媒体类型(Unsupported media type)

8、解决方法是去除Swagger生成接口的Consumes，让其不限制请求类型：

9、修改后重启项目，再次发送请求，这回不是415了，变成了406错误（HTTP 406 Not acceptable，翻译过来是“不能接收”），因为Swagger生成的代码接口，必须指定Accept：

10、所以们在发送请求时在Headers中加入Accept: application/json，再次发送请求，这回返回提200，终于成功了：

11、，但却发现并没有返回内容，BODY是空，原因是Swagger生成的Mock Server只能判断接口是否调用成功，并不能返回需要的数据，如果需要返回一些假数据给前端进行测试，需要手动增加代码，我们在第4步时红色框起来的两个JAVA类，UserApi是对应的接口，UserApiController是接口实现，我们需要修改UserApiController中对应的接口实现，以返回数据：

12、这时我们再次发送接口，返回如下：

到此，我们整个Mock Server的代码已经调通，部署并可以正常使用了。

为什么406会报错，又要我们指定Accept: application/json，这是Swagger的问题，我们需要集成Swagger的源码，修改swagger.js如下：
if (this.type === "POST" || this.type === "GET" || this.type === "PATCH") {
if (this.opts.responseContentType) {
responseContentType = this.opts.responseContentType;
} else {
responseContentType = "application/json";
}
}

再在swagger-ui.js中替换这一行：
opts.responseContentType = $("div select[name=responseContentType]", $(this.el)).val();

替换成：

if($("div select[name=responseContentType]", $(this.el)).val() === undefined) {
opts.responseContentType = opts.parent.model.produces[0];
}
else {
opts.responseContentType = $("div select[name=responseContentType]", $(this.el)).val();
}

这样就从根本敢406报错的问题，再请求时就不用加上Accept: application/json了。

下面附上接口的JSON文件，仅供测试使用。

{
"swagger": "2.0",
"info": {
"description": "2017.11.9上线版本",
"version": "1.0",
"title": "实战指挥平台--基础数据API说明文档",
"contact": {
"name": "智慧消防研发部"
}
},
"host": "127.0.0.1:8090",
"basePath": "/",
"tags": [
{
"name": "validator-controller",
"description": "Validator Controller"
},
{
"name": "user-controller",
"description": "测试UserController"
}
],
"paths": {
"/user": {
"get": {
"tags": [
"user-controller"
],
"summary": "查询个人信息接口",
"description": "查询个人信息接口",
"operationId": "queryUsingGET",
"consumes": [
"application/json"
],
"produces": [
"*/*"
],
"parameters": [
{
"name": "page",
"in": "query",
"description": "page",
"required": true,
"type": "integer",
"format": "int32"
},
{
"name": "count",
"in": "query",
"description": "count",
"required": true,
"type": "integer",
"format": "int32"
},
{
"name": "token",
"in": "header",
"description": "访问凭证",
"required": true,
"type": "string"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/Demo"
}
}
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not Found"
}
}
},
"post": {
"tags": [
"user-controller"
],
"summary": "增加个人信息接口",
"description": "增加个人信息接口",
"operationId": "insertUsingPOST",
"consumes": [
"application/json"
],
"produces": [
"*/*"
],
"parameters": [
{
"in": "body",
"name": "name",
"description": "name",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK"
},
"201": {
"description": "Created"
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not Found"
}
}
}
},
"/validator/query": {
"get": {
"tags": [
"validator-controller"
],
"summary": "query",
"operationId": "queryUsingGET_1",
"consumes": [
"application/json"
],
"produces": [
"*/*"
],
"parameters": [
{
"in": "body",
"name": "page",
"description": "page",
"required": false,
"schema": {
"type": "integer",
"format": "int32"
}
},
{
"name": "count",
"in": "query",
"description": "count",
"required": true,
"type": "integer",
"format": "int32"
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"$ref": "#/definitions/Demo"
}
}
},
"401": {
"description": "Unauthorized"
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not Found"
}
}
}
}
},
"definitions": {
"Demo": {
"type": "object",
"properties": {
"age": {
"type": "string"
},
"id": {
"type": "string"
},
"name": {
"type": "string"
}
}
}
}
}

API详细说明：

作用范围   API   使用位置
对象属性   @ApiModelProperty   用在出入参数对象的字段上
协议集描述   @Api   用于controller类上
协议描述   @ApiOperation   用在controller的方法上
Response集   @ApiResponses   用在controller的方法上
Response   @ApiResponse   用在 @ApiResponses里边
非对象参数集   @ApiImplicitParams   用在controller的方法上
非对象参数描述   @ApiImplicitParam   用在@ApiImplicitParams的方法里边
描述返回对象的意义   @ApiModel   用在返回对象类上

@ApiImplicitParam

属性   取值   作用
paramType        查询参数类型
    path   以地址的形式提交数据
    query   直接跟参数完成自动映射赋值
    body   以流的形式提交仅支持POST
    header   参数在request headers 里边提交
    form   以form表单的形式提交仅支持POST
dataType        参数的数据类型只作为标志说明，并没有实际验证
    Long
    String
name        接收参数名
value        接收参数的意义描述
required        参数是否必填
    true   必填
    false   非必填
defaultValue        默认值

以上就是使用Swagger搭建RESTful风格测试Mock Server，生成Springboot代码的全部过程，整个开发过程其实很简单，但网络上的资料太少，经过不断的踩坑，终于调试成功。
---------------------
作者：二一点
来源：CSDN
原文：https://blog.csdn.net/a78270528/article/details/78530702
版权声明：本文为博主原创文章，转载请附上博文链接！

permanent_2008

关注

0
点赞
踩
0

收藏

觉得还不错? 一键收藏
0
评论
SpringBoot中使用Swagger生成RESTful规范API文档

Swagger为我们提供了非常多的工具，其中最强的还要算这个代码的生成工具。在前后端分离的大环境下，前后端之间订立的接口显得尤为重要，接口在订立之后变动的可能性已经很小，这就要求我们提前去设计接口，也就是我们为前端提供的API。但是我们发现，在开发过程中订立的接口寿命其实很短，这是一件非常严重的事情。因此Swagger为我们提供了另外一种比较优雅的方式：就是你先订立接口，然后再去生成接口；也就...
复制链接

扫一扫