swagger快速开发
转载:https://blog.csdn.net/xxoo00xx00/article/details/77163399
swagger 学习笔记
搭建环境:
- 1,jdk1.8
- 2,idea
- 3,spring-boot-starter-parent版本1.5.6.RELEASE
- 4,springfox-swagger2 And springfox-swagger-ui 版本2.2.2
1快速环境搭建
新建一个工程,file->new->Porject->Spring Initializr->next-如下图所示(idea专业版本,社区版可以到git上复制pom文件)
pom.xml文件中添加如下内容(看清楚再复制,此处不是全部内容)
<properties>
...
<swagger.version>2.2.2</swagger.version>
...
</properties>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagger.version}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger.version}</version>
</dependency>
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
在config目录中新建swagger的配置文件swaggerConfig.java
@EnableSwagger2
@Configuration
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com"))//扫描com路径下的api文档
.paths(PathSelectors.any())//路径判断
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("《----我是title-----》")//标题
.description("《-----我是描述----》:http://www.google.com.hk")//描述
.termsOfServiceUrl("http://www.google.com.hk")//(不可见)条款地址
.contact(new Contact("zz","google.com.hk","123@qq.com"))//作者信息
.version("6.6.6")//版本号
.build();
}
}
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
- 18
- 19
- 20
- 21
- 22
- 23
- 24
- 25
新建实体类User,基本字段如下
@ApiModel(value = "User得实体,----》",reference = "我是参考")
public class User {
@ApiParam(value = "姓名--------------",required = true)
private String name;
//在swagger-ui.html#页面中如果返回User,ModelModel Schema选项卡可见
@ApiModelProperty(value = "id",dataType = "String")
private String id;
//在http://localhost:8080/v2/api-docs最后一行的实体可见
@ApiModelProperty(value = "年龄----------",required = true)
private Integer age;
...此处省略set和get方法
}
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
在controller包立新建TestController,内容如下
@Api(value = "API - VehiclesController", description = "用户接口详情")
@RestController
@RequestMapping("/test")
public class TestController {
static Map<String, User> users = Collections.synchronizedMap(new HashMap<String,User>());
@ApiOperation(value="获取用户列表", notes="")
@ApiResponses(value = {
@ApiResponse(code = 200, message = "Successful — 请求已完成"),
@ApiResponse(code = 400, message = "请求中有语法问题,或不能满足请求"),
@ApiResponse(code = 401, message = "未授权客户机访问数据"),
@ApiResponse(code = 404, message = "服务器找不到给定的资源;文档不存在"),
@ApiResponse(code = 500, message = "服务器不能完成请求")}
)
@RequestMapping(value={""}, method= RequestMethod.GET)
public List<User> getUserList() {
List<User> r = new ArrayList<User>(users.values());
return r;
}
....此处省略n行代码
}
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 17
- 18
- 19
- 20
- 21
- 22
- 23
- 24
- 25
浏览改地址,访问主页面:http://localhost:8080/swagger-ui.html#
浏览改地址,访问sagger专有jsonAPI: http://localhost:8080/v2/api-docs
2常用注释描述
上半部
下半部
下下部
3全部注释列表
@Api
Api 标记可以标记一个Controller类做为swagger 文档资源,使用方式
属性名称 | 备注 |
---|---|
value | url的路径值 |
tags | 如果设置这个值、value的值会被覆盖 |
description | 对api资源的描述 |
basePath | 基本路径可以不配置 |
position | 如果配置多个Api 想改变显示的顺序位置 |
produces | For example, “application/json, application/xml” |
consumes | For example, “application/json, application/xml” |
protocols | Possible values: http, https, ws, wss. |
authorizations | 高级特性认证时配置 |
hidden | 配置为true 将在文档中隐藏 |
@ApiOperation每一个url资源的定义,使用方式
属性名称 | 备注 |
---|---|
value | url的路径值 |
tags | 如果设置这个值、value的值会被覆盖 |
description | 对api资源的描述 |
basePath | 基本路径可以不配置 |
position | 如果配置多个Api 想改变显示的顺序位置 |
produces | For example, “application/json, application/xml” |
consumes | For example, “application/json, application/xml” |
protocols | Possible values: http, https, ws, wss. |
authorizations | 高级特性认证时配置 |
hidden | 配置为true 将在文档中隐藏 |
response | 返回的对象 |
responseContainer | 这些对象是有效的 “List”, “Set” or “Map”.,其他无效 |
httpMethod | “GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH” |
code | http的状态码 默认 200 |
extensions | 扩展属性 |
@ApiParam标记
public ResponseEntity createUser(@RequestBody @ApiParam(value = “user”, required = true) User user)
属性名称 | 备注 |
---|---|
name | 属性名称 |
value | 属性值 |
defaultValue | 默认属性值 |
allowableValues | 可以不配置 |
required | 是否属性必填 |
access | 不过多描述 |
allowMultiple | 默认为false |
hidden | 隐藏该属性 |
example | 举例子 |
@ApiImplicitParam对容器的描述
属性名称 | 备注 |
---|---|
name | 属性名称 |
value | 属性值 |
defaultValue | 默认值 |
allowableValues | 可以不可配置 |
required | 是否属性必填 |
access | 不可过多描述 |
allowMutiple | 默认为false |
dataType | 数据类型 |
paramType | 参数类型 |
@ApiResponse
属性名称 | 备注 |
---|---|
code | http的状态码 |
message | 描述 |
response | 默认响应类 Void |
reference | 参考ApiOperation中配置 |
responseHeaders | 参考 ResponseHeader 属性配置说明 |
responseContainer | 参考ApiOperation中配置 |
@ResponseHeader(name=”head1”,description=”response head conf”)
属性名称 | 备注 |
---|---|
name | 响应头名称 |
description | 头描述 |
response | 默认响应类 Void |
responseContainer | 参考ApiOperation中配置 |
4文档编写规范建议
- entity的描述
@ApiModel(description = “我是描述”,value = “用户”)
对实体的描述
description:在v2/api-docs的实体看到描述,
value的值在@ApiImplicitParam注解中的dataType可用,
@ApiModelProperty(value = “用户姓名”,required = true,dataType = “String”)
private String name;
对字段的描述
value:1,入参和出参的ModelModel Schema选项卡可见,2,在v2/api-docs的实体字段描述可见
required:该属性是否必填写
dataType:该字段的数据类型
- controller的描述
@Api(value = “API”, description = “用户接口详情”,tags=”A”)
对controler的描述
value:访问某个controller的url的根路径值
description:对于该controller的的大概描述
tags:把api接口进行分分组
@ApiOperation(value = “获取用户详细信息”, notes = “根据url的id来获取用户详细信息”,httpMethod =”GET”)
对该方法的描述
value:主页面中对该接口的描述,位置在接口的最右边
notes:点开接口后,第一段描述。
httpMethod:HTTP请求的动作名,可选值有:”GET”, “HEAD”, “POST”, “PUT”, “DELETE”, “OPTIONS” and “PATCH”。
@ApiImplicitParam(name = “id”, value = “用户ID”, required = true, dataType = “String”, paramType = “path”)
对参数的描述,如果多个参数需要用@ApiImplicitParams对其进行包裹
name:参数名称
value:参数的简短描述
required:是否必须传递的参数
dataType:参数类型,可以为类名,也可以为基本类型(String,int,Boolean)
paramType:参数的传入(请求)类型,可选的值有path, query, body, header or form。(如果在路径中提取参数用path比如:在/A/{XXX}路径中得到XXX的值)
@ApiParam(name = “user”, value = “userValue”, required = true)
对参数元信息的说明,一般这个注解只能被使用在JAX-RS 1.x/2.x的综合环境下,和ApiImplicitParam注解类似
required:该参数是否必填
value:该参数的简短介绍
@ApiResponse(code = 200, message = “Successful — 请求已完成”)
返回状态码的描述,如果有多个可以使用@ApiResponses注解进行包裹
code:服务器返回的状态码
message:服务器返回状态码的简短说明
sample:header中传递token
@ApiImplicitParams({@ApiImplicitParam(name = "TOKEN", value = "Authorization token", required = true, dataType = "string", paramType = "header")})
- 1
5,注意事项:
- 路径参数比如一直传递 {id},需要在ApiImplicitParam注解中添加prameType=“path”
- 版本问题,需要删除m2里面的jar包,2.2.2的swagger和1.5.6的spring-boot-prent才是绝配,试过很多最新的包,感觉多多少少都有点问题!
- 入参数和出参数都能用到一个实体类,注意检查@ApiModel的value属性
6参考文档
可能还有其他没有列出的参考文档,见谅
https://gumutianqi1.gitbooks.io/specification-doc/content/tools-doc/spring-boot-swagger2-guide.html
http://www.jianshu.com/p/12f4394462d5
http://blog.didispace.com/springbootswagger2/
https://dzone.com/articles/spring-boot-restful-api-documentation-with-swagger
http://www.jianshu.com/p/b0b19368e4a8
swagger快速开发的更多相关文章
- JEECG 3.7.2版本发布,企业级JAVA快速开发平台
JEECG 3.7.2版本发布 - 微云快速开发平台 JEECG是一款基于代码生成器的J2EE快速开发平台,开源界"小普元"超越传统商业企业级开发平台.引领新的开发模式(Onli ...
- springboot之swagger快速启动
springboot之swagger快速启动 简介 介绍 可能大家都有用过swagger,可以通过ui页面显示接口信息,快速和前端进行联调. 没有接触的小伙伴可以参考官网文章进行了解下demo页面. ...
- .Net Core与Vue.js模块化前后端分离快速开发解决方案(NetModular)
NetModular是什么? NetModular不仅仅是一个框架,它也是一整套的模块化与前后端分离的快速开发的解决方案,目标是致力于开箱即用,让开发人员完全专注于业务开发,不需要关心底层封装和实现. ...
- 在线Online表单来了!JeecgBoot 2.1 版本发布——基于SpringBoot+AntDesign的快速开发平台
项目介绍 Jeecg-Boot 是一款基于SpringBoot+代码生成器的快速开发平台! 采用前后端分离架构:SpringBoot,Ant-Design-Vue,Mybatis,Shiro,JWT. ...
- 程序小白如何快速开发OA办公系统
对于企业开发oa办公系统,成本高,周期长.有些企业花高价购买,购买后受制于软件商,很多功能只能按原来设计需求走,无法升级或者升级慢.这些由于软件商的开发效率低难以及时地响应企业的需求变化,所以就有可能 ...
- java快速开发平台可视化开发表单
XJR java快速开发平台,简单的理解就是:开发人员以某种编程语言或者某几种编程语言(比如:目前流行的多种web技术,包括springboot, JPA,Druid, Activiti,Lombok ...
- 4款java快速开发平台推荐
JBoss Seam JBoss Seam,算得上是Java开源框架里面最优秀的快速开发框架之一. Seam框架非常出色,尤其是他的组件机制设计的很有匠心,真不愧是Gavin King精心打造的框架了 ...
- 基于领域驱动设计(DDD)超轻量级快速开发架构
smartadmin.core.urf 这个项目是基于asp.net core 3.1(最新)基础上参照领域驱动设计(DDD)的理念,并参考目前最为了流行的abp架构开发的一套轻量级的快速开发web ...
- 基于ABP开发框架的技术点分析和项目快速开发实现
在我们开发各种项目应用的时候,往往都是基于一定框架进行,同时配合专用的代码生成工具,都是为了快速按照固定模式开发项目,事半功倍,本篇随笔对基于ABP开发框架的技术点进行分析和ABP框架项目快速开发实现 ...
随机推荐
- 洛谷P1550 [USACO08OCT]打井Watering Hole
P1550 [USACO08OCT]打井Watering Hole 题目背景 John的农场缺水了!!! 题目描述 Farmer John has decided to bring water to ...
- Linux常用命令--用户管理,文件权限,打包命令等
幕布链接 Linux常用命令--用户管理,文件权限,打包命令等
- 犯得错误QAQ
1.十年OI一场空,不开longlong见祖宗(丢过150分) 2.计算完了再开数组,开的足足的.不要少开0:(丢过一共200分) 3.最大值,最小值一定开成7个f.(丢了20分). 4.freope ...
- 【Linux】DNS服务-BIND基础配置
1.BIND简介 现在使用最为广泛的DNS服务器软件是BIND(Berkeley Internet Name Domain),最早有伯克利大学的一名学生编写,现在最新的版本是9,有ISC(Intern ...
- [Beta阶段]第一次Scrum Meeting
Scrum Meeting博客目录 [Beta阶段]第一次Scrum Meeting 基本信息 名称 时间 地点 时长 第一次Scrum Meeting 19/04/29 大运村寝室6楼 70min ...
- Android HttpURLConnection的使用+Handler的原理及典型应用
1.介绍 总结:HttpURLConnection用来发送和接收数据. 2.ANR异常报错 (1)ANR(Application not response) 应用无响应, 主线程(UI线程) (2)如 ...
- python之列表,元组,字典。
在博主学习列表,元组以及字典的时候,经常搞混这三者.因为他们都是用括号表示的.分别是[],(),{}. 列表(list): [1,'abc',1.26,[1,2,3],(1,2,3),{'age:18 ...
- 215 Kth Largest Element in an Array 快排
题目:在无序的数组中找到第k大的元素,也就是若长度为n的数组从小到大排列时,下标为n-k的元素. 注意Example2:第4大的元素是4,也就是数组中出现的两个5分别是第2大和第3大的数字. 解法一: ...
- UESTC - 1357 前缀和维护
有点小细节需要注意 sum实时维护有效的连续和 /*H E A D*/ ll dp1[maxn],dp2[maxn]; ll a[maxn],n,sum; int main(){ while(~iin ...
- 腾讯云(Linux)安装.net core sdk2.1、net core runtime2.1
按照微软指令安装: sdk2.1:https://www.microsoft.com/net/download/linux-package-manager/centos/sdk-current 1. ...