-
Swagger2
2019-04-23 15:46:23pom.xml: <!--swagger--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <v...pom.xml:
<!--swagger--> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.6.1</version> </dependency>
Swagger2类:
package com.example.shopgoods.common.config; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.context.annotation.Profile; import springfox.documentation.builders.ApiInfoBuilder; import springfox.documentation.builders.PathSelectors; import springfox.documentation.builders.RequestHandlerSelectors; import springfox.documentation.service.ApiInfo; import springfox.documentation.spi.DocumentationType; import springfox.documentation.spring.web.plugins.Docket; import springfox.documentation.swagger2.annotations.EnableSwagger2; /** * @Author: zp * @Date: 2019/4/19 13:43 * @Description: */ /** * Swagger2配置类 * 在与spring boot集成时,放在与Application.java同级的目录下。 * 通过@Configuration注解,让Spring来加载该类配置。 * 再通过@EnableSwagger2注解来启用Swagger2。 */ @Configuration @EnableSwagger2 @Profile({"dev"}) public class Swagger2 { /** * 创建API应用 * apiInfo() 增加API相关信息 * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现, * 本例采用指定扫描的包路径来定义指定要建立API的目录。 * * @return */ @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(apiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.example.controller")) .paths(PathSelectors.any()) .build(); } /** * 创建该API的基本信息(这些基本信息会展现在文档页面中) * 访问地址:http://项目实际地址/swagger-ui.html * @return */ private ApiInfo apiInfo() { return new ApiInfoBuilder() .title("Spring Boot集成Swagger2构建RESTful APIs") .description("更多请关注<Swagger使用指南>") .termsOfServiceUrl("https://blog.csdn.net/sanyaoxu_2/article/details/80555328") .version("2.6.1") .build(); } }
Controller层代码列如:
/** * 下单校验接口 * @param checkOrderRequestDTO * @return */ @ApiOperation(value = "下单校验接口") @PostMapping("/check") @ApiImplicitParam(name = "checkOrderRequestDTO", value = "下单时商品信息", dataType = "CheckOrderRequestDTO") public Result<Boolean> checkOrder(@RequestBody CheckOrderRequestDTO checkOrderRequestDTO) { return Boolean.TRUE; }
入参和出参的注释:
package com.ecshop.common.dto; import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; import lombok.Data; import javax.validation.constraints.NotNull; /** * @Author: zp * @Date: 2019/4/17 18:06 * @Description: */ @Data @ApiModel(value = "CheckOrderRequestDTO", description = "下单时商品信息") public class CheckOrderRequestDTO { //商品id @NotNull(message = "商品id不能为null") @ApiModelProperty(value = "商品id") private Integer goodsId; //商品属性id @NotNull(message = "商品属性id不能为null") @ApiModelProperty(value = "商品属性id") private Integer goodsAttrId; //下单时购买的商品数量 @NotNull(message = "商品数量不能为null") @ApiModelProperty(value = "商品数量") private Integer goodsNumber; }
完成上述代码添加上,启动Spring Boot程序,访问:http://localhost:8080/swagger-ui.html
相关文献:
Swagger使用指南
Swagger与RestFul 集成 以及 注解使用Demo
微服务之Swagger
关于Swagger @ApiModel 返回内容注释不显示问题 -
swagger2
2017-06-27 20:19:47swagger需要导入swagger相关页面,...swagger2更近一步,只需要做几个配置即可,更简单,更易用。项目基于spring-boot实现,下面指定配置点pom.xml依赖 <!-- swagger 框架依赖 --> <groupId>io.springfox</groupId>swagger需要导入swagger相关页面,比较麻烦。
swagger2更近一步,只需要做几个配置即可,更简单,更易用。项目基于spring-boot实现,下面指定配置点
pom.xml依赖
<!-- swagger 框架依赖 --> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger2</artifactId> <version>2.6.1</version> </dependency> <dependency> <groupId>io.springfox</groupId> <artifactId>springfox-swagger-ui</artifactId> <version>2.6.1</version> </dependency>
swagger2配置类
/** * * swagger2使用说明: @Api:用在类上,说明该类的作用 @ApiOperation:用在方法上,说明方法的作用 @ApiImplicitParams:用在方法上包含一组参数说明 @ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面 paramType:参数放在哪个地方 header-->请求参数的获取:@RequestHeader query-->请求参数的获取:@RequestParam path(用于restful接口)-->请求参数的获取:@PathVariable body(不常用) form(不常用) name:参数名 dataType:参数类型 required:参数是否必须传 value:参数的意思 defaultValue:参数的默认值 @ApiResponses:用于表示一组响应 @ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息 code:数字,例如400 message:信息,例如"请求参数没填好" response:抛出异常的类 @ApiModel:描述一个Model的信息(这种一般用在post创建的时候,使用@RequestBody这样的场景,请求参数无法使用@ApiImplicitParam注解进行描述的时候) @ApiModelProperty:描述一个model的属性 * * */ @Configuration @EnableSwagger2 public class SwaggerConfig2 { @Bean public Docket createRestApi() { return new Docket(DocumentationType.SWAGGER_2) .apiInfo(createApiInfo()) .select() .apis(RequestHandlerSelectors.basePackage("com.aaa.bbb")) .paths(PathSelectors.any()) .build(); } private ApiInfo createApiInfo() { return new ApiInfoBuilder().title("AAA RESTful API 说明文档") .version("1.0") .build(); } }
Application类中,配置如下
@EnableSwagger2 @SpringBootApplication @EnableAutoConfiguration public class AAAApplication { public static void main(String[] args){ xxx.. } }
controller中
@Api(value = "aaa", description = "这是aaa") @RestController @RequestMapping("/aaa") @CrossOrigin(allowedHeaders="*", allowCredentials="true") public class AAAController { @RequestMapping(value = "/bbb", method = RequestMethod.GET) @ResponseBody @ApiOperation(value = "bbb", notes = "这是bbb", httpMethod = "GET") public void getInstanceList(HttpServletResponse response, @ApiParam("ccc ID") @RequestParam(value = "ccc_id") int ccc_id){ sout。。。。 } }
直接访问
http://服务名:8080/swagger-ui.html
即可
-
-
swagger2 注解说明 ( @ApiImplicitParams )
2018-10-17 12:25:36@Api:用在请求的类上,表示对类的说明 tags="说明该类的作用,可以在UI界面上看到的注解" value="该参数没什么意义,在UI界面上也看到,所以不需要配置" @ApiOperation:用在请求的方法上,说明方法的用途、...前些天发现了一个巨牛的人工智能学习网站,通俗易懂,风趣幽默,忍不住分享一下给大家。点击跳转到教程。
@Api:用在请求的类上,表示对类的说明 tags="说明该类的作用,可以在UI界面上看到的注解" value="该参数没什么意义,在UI界面上也看到,所以不需要配置" @ApiOperation:用在请求的方法上,说明方法的用途、作用 value="说明方法的用途、作用" notes="方法的备注说明" @ApiImplicitParams:用在请求的方法上,表示一组参数说明 @ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面 name:参数名 value:参数的汉字说明、解释 required:参数是否必须传 paramType:参数放在哪个地方 · header --> 请求参数的获取:@RequestHeader · query --> 请求参数的获取:@RequestParam · path(用于restful接口)--> 请求参数的获取:@PathVariable · body(不常用) · form(不常用) dataType:参数类型,默认String,其它值dataType="Integer" defaultValue:参数的默认值 @ApiResponses:用在请求的方法上,表示一组响应 @ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息 code:数字,例如400 message:信息,例如"请求参数没填好" response:抛出异常的类 @ApiModel:用于响应类上,表示一个返回响应数据的信息 (这种一般用在post创建的时候,使用@RequestBody这样的场景, 请求参数无法使用@ApiImplicitParam注解进行描述的时候) @ApiModelProperty:用在属性上,描述响应类的属性
1、@Api:用在请求的类上,说明该类的作用
tags="说明该类的作用"
value="该参数没什么意义,所以不需要配置"
示例:@Api(tags="APP用户注册Controller")
2、@ApiOperation:用在请求的方法上,说明方法的作用
@ApiOperation:"用在请求的方法上,说明方法的作用"
value="说明方法的作用"
notes="方法的备注说明"
示例:@ApiOperation(value="用户注册",notes="手机号、密码都是必输项,年龄随边填,但必须是数字")
3、@ApiImplicitParams:用在请求的方法上,包含一组参数说明
@ApiImplicitParams:用在请求的方法上,包含一组参数说明
@ApiImplicitParam:用在 @ApiImplicitParams 注解中,指定一个请求参数的配置信息
name:参数名
value:参数的汉字说明、解释
required:参数是否必须传
paramType:参数放在哪个地方
· header --> 请求参数的获取:@RequestHeader
· query --> 请求参数的获取:@RequestParam
· path(用于restful接口)--> 请求参数的获取:@PathVariable
· body(不常用)
· form(不常用)
dataType:参数类型,默认String,其它值dataType="Integer"
defaultValue:参数的默认值示列:
@ApiImplicitParams({ @ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"), @ApiImplicitParam(name="password",value="密码",required=true,paramType="form"), @ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer") })
4、@ApiResponses:用于请求的方法上,表示一组响应
@ApiResponses:用于请求的方法上,表示一组响应
@ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息
code:数字,例如400
message:信息,例如"请求参数没填好"
response:抛出异常的类
示例:@ApiOperation(value = "select1请求",notes = "多个参数,多种的查询参数类型") @ApiResponses({ @ApiResponse(code=400,message="请求参数没填好"), @ApiResponse(code=404,message="请求路径没有或页面跳转路径不对") })
5、@ApiModel:用于响应类上,表示一个返回响应数据的信息
@ApiModel:用于响应类上,表示一个返回响应数据的信息
(这种一般用在post创建的时候,使用@RequestBody这样的场景,
请求参数无法使用@ApiImplicitParam注解进行描述的时候)
@ApiModelProperty:用在属性上,描述响应类的属性
示例:import io.swagger.annotations.ApiModel; import io.swagger.annotations.ApiModelProperty; import java.io.Serializable; @ApiModel(description= "返回响应数据") public class RestMessage implements Serializable{ @ApiModelProperty(value = "是否成功") private boolean success=true; @ApiModelProperty(value = "返回对象") private Object data; @ApiModelProperty(value = "错误编号") private Integer errCode; @ApiModelProperty(value = "错误信息") private String message; /* getter/setter */ }
-
swagger2 注解说明
2017-11-28 14:23:02swagger2 注解整体说明 @Api:用在请求的类上,表示对类的说明 tags=&amp;amp;quot;说明该类的作用,可以在UI界面上看到的注解&amp;amp;quot; value=&amp;amp;quot;该参数没什么...文章目录
1、maven依赖
<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> <dependency> <groupId>com.github.xiaoymin</groupId> <artifactId>swagger-bootstrap-ui</artifactId> <version>1.9.6</version> </dependency>
1、swagger2 注解整体说明
用于controller类上:
注解 说明 @Api 对请求类的说明 用于方法上面(说明参数的含义):
注解 说明 @ApiOperation 方法的说明 @ApiImplicitParams、@ApiImplicitParam 方法的参数的说明;@ApiImplicitParams 用于指定单个参数的说明 用于方法上面(返回参数或对象的说明):
注解 说明 @ApiResponses、@ApiResponse 方法返回值的说明 ;@ApiResponses 用于指定单个参数的说明 对象类:
注解 说明 @ApiModel 用在JavaBean类上,说明JavaBean的 用途 @ApiModelProperty 用在JavaBean类的属性上面,说明此属性的的含议 2、@Api:请求类的说明
@Api:放在 请求的类上,与 @Controller 并列,说明类的作用,如用户模块,订单类等。 tags="说明该类的作用" value="该参数没什么意义,所以不需要配置"
示例:
@Api(tags="订单模块") @Controller public class OrderController { }
@Api
其它属性配置:属性名称 备注 value url的路径值 tags 如果设置这个值、value的值会被覆盖 description 对api资源的描述 basePath 基本路径 position 如果配置多个Api 想改变显示的顺序位置 produces 如, “application/json, application/xml” consumes 如, “application/json, application/xml” protocols 协议类型,如: http, https, ws, wss. authorizations 高级特性认证时配置 hidden 配置为true ,将在文档中隐藏 3、@ApiOperation:方法的说明
@ApiOperation:"用在请求的方法上,说明方法的作用" value="说明方法的作用" notes="方法的备注说明"
3.1、@ApiImplicitParams、@ApiImplicitParam:方法参数的说明
@ApiImplicitParams:用在请求的方法上,包含一组参数说明 @ApiImplicitParam:对单个参数的说明 name:参数名 value:参数的说明、描述 required:参数是否必须必填 paramType:参数放在哪个地方 · query --> 请求参数的获取:@RequestParam · header --> 请求参数的获取:@RequestHeader · path(用于restful接口)--> 请求参数的获取:@PathVariable · body(请求体)--> @RequestBody User user · form(普通表单提交) dataType:参数类型,默认String,其它值dataType="Integer" defaultValue:参数的默认值
示列:
@Api(tags="用户模块") @Controller public class UserController { @ApiOperation(value="用户登录",notes="随边说点啥") @ApiImplicitParams({ @ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"), @ApiImplicitParam(name="password",value="密码",required=true,paramType="form"), @ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer") }) @PostMapping("/login") public JsonResult login(@RequestParam String mobile, @RequestParam String password, @RequestParam Integer age){ //... return JsonResult.ok(map); } }
4、@ApiResponses、@ApiResponse:方法返回值的状态码说明
@ApiResponses:方法返回对象的说明 @ApiResponse:每个参数的说明 code:数字,例如400 message:信息,例如"请求参数没填好" response:抛出异常的类
示例:
@Api(tags="用户模块") @Controller public class UserController { @ApiOperation("获取用户信息") @ApiImplicitParams({ @ApiImplicitParam(paramType="query", name="userId", dataType="String", required=true, value="用户Id") }) @ApiResponses({ @ApiResponse(code = 200, message = "请求成功"), @ApiResponse(code = 400, message = "请求参数没填好"), @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对") }) @ResponseBody @RequestMapping("/list") public JsonResult list(@RequestParam String userId) { ... return JsonResult.ok().put("page", pageUtil); } }
5、@ApiModel:用于JavaBean上面,表示对JavaBean 的功能描述
@ApiModel
的用途有2个:- 当请求数据描述,即
@RequestBody
时, 用于封装请求(包括数据的各种校验)数据; - 当响应值是对象时,即
@ResponseBody
时,用于返回值对象的描述。
5.1、当请求数据描述时,
@RequestBody
时的使用@ApiModel(description = "用户登录") public class UserLoginVO implements Serializable { private static final long serialVersionUID = 1L; @ApiModelProperty(value = "用户名",required=true) private String username; @ApiModelProperty(value = "密码",required=true) private String password; // getter/setter省略 }
@Api(tags="用户模块") @Controller public class UserController { @ApiOperation(value = "用户登录", notes = "") @PostMapping(value = "/login") public R login(@RequestBody UserLoginVO userLoginVO) { User user=userSerivce.login(userLoginVO); return R.okData(user); } }
5.2、@ApiModelProperty:用在JavaBean类的属性上面,说明属性的含义
示例:
@ApiModel(description= "返回响应数据") public class RestMessage implements Serializable{ @ApiModelProperty(value = "是否成功",required=true) private boolean success=true; @ApiModelProperty(value = "错误码") private Integer errCode; @ApiModelProperty(value = "提示信息") private String message; @ApiModelProperty(value = "数据") private Object data; /* getter/setter 略*/ }
http://localhost:5680/zxmall/swagger-ui.html
- 当请求数据描述,即
-
swagger2Demo,swagger
2018-07-06 12:27:04swagger2Demo,swagger,这个是写的一个demo,用于调试接口swagger确实好用,jdk1.8的,欢迎下载, -
Swagger2离线文档:swagger2markup代码和插件方式
2020-04-14 09:31:45SpringBoot集成Swagger2,以及Swagger2常用API Swagger2离线文档:PDF和Html5格式 SpringBoot整合Shiro,Swagger2页面样式加载不出来问题 Swagger2Markup简介 Swagger2Markup是Github上的一个开源项目。该项目... -
Swagger2常用注解说明
2020-07-20 23:40:14文章目录Swagger2简介使用Swagger解决的问题Spring Boot集成Swagger2添加依赖添加Swagger2Config配置类编写接口用户DTO用户controller访问接口文档Swagger2常用注解说明Controller相关注解@Api接口相关注解@... -
SpringBoot整合Swagger2,再也不用维护接口文档了!
2019-03-24 12:04:50前后端分离后,维护接口文档基本上是必不可少的工作。一个理想的状态是设计好后,接口文档发给前端和后端,...还好,有一些工具可以减轻我们的工作量,Swagger2就是其中之一,至于其他类似功能但是却收费的软件,... -
swagger2 配置访问路径_Swagger2使用详解
2021-01-07 19:17:58作者:ThinkWonhttps://blog.csdn.net/ThinkWon/article/details/107477801文章目录 一、Swagger2简介 二、使用Swagger2解决的问题 三、SpringBoot集成Swagger2 1.添加依赖 2.添加Swagger... -
SpringBoot集成Swagger2,以及Swagger2常用API
2018-01-08 20:19:41为什么选择Swagger2 接口文档在线自动生成 接口在线调试功能 文档与代码可以保持同步(因为文档的方法,参数和模型紧密集成到服务端的代码) maven依赖 <properties> <!-- swagger.version --> <... -
Swagger3.0与Swagger2对比
2020-08-07 17:00:59Swagger3.0与Swagger2对比前言使用流程1.导入Maven坐标2.配置 前言 在写项目的时候,想到swagger3已经更新了,于是想着尝鲜使用下,的确省去了很多配置。 这里写下使用流程。 参考:Springfox 3.0.0(包含springfox-... -
swagger2maven依赖_swagger2技术
2021-01-17 12:41:111.什么是Swagger2?Swagger是一个RESTFUL 接口的文档在线自动生成和功能测试的框架。Swagger 是一个规范和完整的框架。用于生成、描述、调用和可视化RestFul风格的Web服务。总体目标是使客户端和文件系统作为服务器以... -
springboot集成Swagger2以及Swagger2的配置详解
2020-10-09 11:50:07Swagger2 走出六亲不认的步伐。 springboot集成Swagger2 添加依赖 springboot项目中,引入swagger2:在pom.xml中,增加如下依赖 <properties> <swagger.version>2.9.2</swagger.version> <...