springboot使用swagger2生成开发文档
一、引入jar包
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
二、创建swagger2的配置类
@Configuration
@EnableSwagger2
public class Swagger2 {
@Bean
public Docket createRestApi(){
//多个暴露路径时
//com.google.common.base.Predicate<RequestHandler> selector1 = RequestHandlerSelectors.basePackage("com.dingzi.project.Controller");
//com.google.common.base.Predicate<RequestHandler> selector2 = RequestHandlerSelectors.basePackage("com.dingzi.project.apiController");
return new Docket(DocumentationType.SWAGGER_2)
//API基本信息
.apiInfo(apiInfo())
.select()
//暴露路径为当前包路径
.apis(RequestHandlerSelectors.basePackage("com.example.learn.swagger2"))
//多个暴露路径
//.apis(Predicates.or(selector1,selector2))
.paths(PathSelectors.any())
.build();
} //构建 api文档的详细信息函数,注意这里的注解引用的是哪个
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//页面标题
.title("Spring Boot 测试使用 Swagger2")
//创建人、路径、邮箱
.contact(new Contact("dingzi", "", ""))
//版本号
.version("1.0")
//描述
.description("API 描述")
.build();
}
}
三、使用swagger2注解
@RestController
@RequestMapping("/api")
@Api("swagger2Controller测试api")
@Slf4j
public class SwaggerDemoController { @Autowired
private UserService userService; @ApiOperation(value = "根据id查询用户", notes = "查询用户信息")
@ApiImplicitParam(name = "id",value = "用户id",required = true)
@RequestMapping(value = "/getuser/{id}",method = RequestMethod.GET)
public User getUser(@PathVariable String id){
return userService.getUser(id);
}
}
- 在controller上的注解
@Api:用在controller上,表示对类的说明。一般为
@Api("swagger2Controller测试api") 常用参数:
tags="说明该类的作用,非空时将覆盖value的值"
value="描述类的作用"
其他参数:
description 对api资源的描述,在1.5版本后不再支持
basePath 基本路径可以不配置,在1.5版本后不再支持
position 如果配置多个Api 想改变显示的顺序位置,在1.5版本后不再支持
produces 设置MIME类型列表(output),例:"application/json, application/xml",默认为空
consumes 设置MIME类型列表(input),例:"application/json, application/xml",默认为空
protocols 设置特定协议,例:http, https, ws, wss。
authorizations 获取授权列表(安全声明),如果未设置,则返回一个空的授权值。
hidden 默认为false, 配置为true 将在文档中隐藏
- 用于方法上(说明参数的含义)
@ApiOperation:方法的说明 一般为
@ApiOperation(value = "根据id查询用户", notes = "查询用户信息")
常用参数:
value="说明方法的用途、作用"
notes="方法的备注说明"
其他参数:
tags 操作标签,非空时将覆盖value的值
response 响应类型(即返回对象)
responseContainer 声明包装的响应容器(返回对象类型)。有效值为 "List", "Set" or "Map"。
responseReference 指定对响应类型的引用。将覆盖任何指定的response()类
httpMethod 指定HTTP方法,"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"
position 如果配置多个Api 想改变显示的顺序位置,在1.5版本后不再支持
nickname 第三方工具唯一标识,默认为空
produces 设置MIME类型列表(output),例:"application/json, application/xml",默认为空
consumes 设置MIME类型列表(input),例:"application/json, application/xml",默认为空
protocols 设置特定协议,例:http, https, ws, wss。
authorizations 获取授权列表(安全声明),如果未设置,则返回一个空的授权值。
hidden 默认为false, 配置为true 将在文档中隐藏
responseHeaders 响应头列表
code 响应的HTTP状态代码。默认 200
extensions 扩展属性列表数组
2、@ApiImplicitParams、@ApiImplicitParam:方法的参数的说明;@ApiImplicitParam 用于指定单个参数的说明,@ApiImplicitParams包含多个@ApiImplicitParam 一般为
@ApiImplicitParam(name = "id",value = "用户id",required = true)
@ApiImplicitParams({
@ApiImplicitParam(name="name",value="用户名",dataType="string", paramType = "query",example="xingguo"),
@ApiImplicitParam(name="id",value="用户id",dataType="long", paramType = "query")})
name:参数名,参数名称可以覆盖方法参数名称,路径参数必须与方法参数一致
value:参数的汉字说明、解释
required:参数是否必须传,默认为false [路径参数必填]
paramType:参数放在哪个地方
·header --> 请求参数的获取:
@RequestHeader
·query --> 请求参数的获取:
@RequestParam
·path(用于restful接口)--> 请求参数的获取:
@PathVariable
·body(不常用)
·form(不常用)
dataType:参数类型,默认String,其它值dataType="Integer"
defaultValue:参数的默认值
3、@ApiResponses、@ApiResponse:方法返回值的状态码说明 一般为
@ApiResponse(code = 200, message = "请求成功");
@ApiResponses({
@ApiResponse(code = 200, message = "请求成功"),
@ApiResponse(code = 400, message = "请求参数没填好"),
@ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
})
@ApiResponses:方法返回对象的说明
@ApiResponse:每个参数的说明
code:数字,例如400
message:信息,例如"请求参数没填好"
response:抛出异常的类
- 用于对象上(当请求数据描述,即
@RequestBody
时, 用于封装请求(包括数据的各种校验)数据;当响应值是对象时,即@ResponseBody
时,用于返回值对象的描述。)
1、@ApiModel:用于JavaBean上面,表示对JavaBean 的功能描述 一般为
@ApiModel(value="用户登录信息", description="用于判断用户是否存在")
参数: value–表示对象名
description–描述
2、@ApiModelProperty:用在JavaBean类的属性上面,说明属性的含义 一般为
@ApiModelProperty(value="用户名") 参数: value–字段说明
name–重写属性名字
dataType–重写属性类型
required–是否必填
example–举例说明
hidden–隐藏
- 用于方法参数上
1、@ApiParam() 用于方法,参数,字段说明;表示对参数的添加元数据(说明或是否必填等) 一般为
@ApiParam(name="id",value="用户id",required=true) 参数为:name–参数名
value–参数说明
required–是否必填
springboot使用swagger2生成开发文档的更多相关文章
- Springboot集成swagger2生成接口文档
[转载请注明]: 原文出处:https://www.cnblogs.com/jstarseven/p/11509884.html 作者:jstarseven 码字挺辛苦的..... 一 ...
- 项目管理之 使用 appledoc 生成开发文档
写项目时通常会遇到要求写开发文档的需求,但是就源代码来说,文档最好和源码在一起,这样更新起来更加方便和顺手.Objective-C 有一些文档管理工具,doxygen, headdoc 和 apple ...
- .NET6使用DOCFX自动生成开发文档
本文内容来自我写的开源电子书<WoW C#>,现在正在编写中,可以去WOW-Csharp/学习路径总结.md at master · sogeisetsu/WOW-Csharp (gith ...
- 【netcore基础】.Net core使用swagger自动生成开发文档
之前写过一篇 .Net 版本的博客 https://www.cnblogs.com/jhli/p/8317566.html 现在只不过用了 netcore 之后的版本,其实差不多 netcore版本的 ...
- [技巧]使用Xcode集成的HeaderDoc自动生成注释和开发文档
[技巧]使用Xcode集成的HeaderDoc自动生成注释和开发文档 Doxygen本来是一个很好的工具,可是我感觉在mac系统下,如果用doxygen最后生成的CHM文件感觉就不是那么恰当, ...
- windows下使用 ApiGen 生成php项目的开发文档
之前使用 PHPDocument 生成过开发文档,但是界面看着不爽,遂尝试了 ApiGen 生成,不得不说界面看着舒服多了,下面说说安装和使用的方法. ApiGen官网: http://www.api ...
- SpringBoot+rest接口+swagger2生成API文档+validator+mybatis+aop+国际化
代码地址:JillWen_SpringBootDemo mybatis 1. 添加依赖: <dependency> <groupId>org.mybatis.spring.bo ...
- 基于x86架构的内核Demo的详细开发文档
http://hurlex.0xffffff.org/ 这里是hurlex这个基于x86架构的内核Demo的详细开发文档, 包含PDF文档和生成PDF的XeLaTex源码和文档每章节的阶段代码. 你可 ...
- Mego开发文档 - 索引
Mego 开发文档 Mego 快速概述 主要特性 获取Mego 使用流程 模型 查询 保存数据 入门 Mego 快速开始 创建项目 安装Nuget包 创建连接字符串 创建模型及数据上下文(添加引用) ...
随机推荐
- 腾讯云函数免费搭建onedrive网盘
目录 腾讯云函数 介绍 真免费? 搭建教程 准备条件 创建云函数 创建触发器 配置SecretId和SecretKey 添加onedriver盘 自定义域名 访问路径处理 总结 搭建期间遇到的问题 想 ...
- 使用websocket连接(对接)asp.net core signalr
使用通用websocket连接asp.net core signalr 一.背景介绍 signalr的功能很强大,可以为我们实现websocket服务端节省不少的时间.但是可能由于不同的环境,我们在对 ...
- 简述BIO到NIO的过程
BIO到NIO的图示
- skywalking8.1.0(一) 安装与部署
skywalking部署 背景介绍 目前公司后端服务全部为微服务并运行在kubernetes集群上,而大量的微服务的背后拥有很复杂的调用关系,纵使你是公司的资深开发也很难理清每一个后端服务之间的依赖关 ...
- PPT神器
今天要给大家推荐一款开挂一般的 PPT 插件:iSlide 强烈推荐大家下载使用哈,绝对分分钟让你做出美观大气的 PPT! 不管是老师.学生还是公司人员,PPT 都是必须要掌握的技能,然而要 ...
- 如何给office2019安装visio2019
1.关于版本,如果你的office2019推荐安装2019visio,2019office只有安装2019visio才不会互斥 下载地址是百度网盘传送,也要安装教程,可是里面的激活器用不了 https ...
- SpringBoot + Swagger Demo
Swagger是什么? Swagger 是一个规范且完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务. Swagger 的目标是对 REST API 定义一个标准且和语 ...
- 联考day7 C. 树和森林 树形DP
题目描述 样例 样例输入 8 5 BBWWWBBW 1 2 2 3 4 5 6 7 7 8 样例输出 84 2 1 4 样例解释 分析 首先,我们要预处理出一个点到该联通块内所有点的距离之和 \(f\ ...
- Photoshop如何安装蓝湖插件
Photoshop如何安装蓝湖插件 下载蓝湖插件 直通车:蓝湖Photoshop插件: Photoshop版本要求为cc2017以上, 下载后是一个zip格式的文件,我们需要解压. 下载的文件 解压后 ...
- 第一行代码中RecyclerView添加依赖库问题
现在更新到 implementation 'com.android.support:recyclerview-v7:29.2.1' 记得点Sync Now来进行同步.