swagger配置及注解详解
2024-05-16 02:08:07
swagger配置及注解详解
1.加入依赖的jar包
<!--引入swagger的依赖--><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>
2.配置swagger配置文件
添加配置文件如下：
package com.hubiao.pay.common.merchant.config;import io.swagger.annotations.ApiOperation;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
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;/*** Swagger2的接口配置** @author hubiao*/
@Configuration
@ConditionalOnProperty(prefix = "swagger",value = {"enable"},havingValue = "true")
@EnableSwagger2
public class SwaggerConfig {/*** 创建API*/@Beanpublic Docket createRestApi() {return new Docket( DocumentationType.SWAGGER_2 )// 用来创建该API的基本信息，展示在文档的页面中（自定义展示的信息）.apiInfo( apiInfo() )// 设置哪些接口暴露给Swagger展示.select()// (第一种方式)扫描所有有注解的api，用这种方式更灵活.apis( RequestHandlerSelectors.withMethodAnnotation( ApiOperation.class ) )// (第二种方式)扫描指定包中的swagger注解//.apis(RequestHandlerSelectors.basePackage("com.hubiao.pay.merchant.controller"))// (第三种方式)扫描所有 //.apis(RequestHandlerSelectors.any()).paths( PathSelectors.any() ).build();}/*** 添加摘要信息*/private ApiInfo apiInfo() {// 用ApiInfoBuilder进行定制return new ApiInfoBuilder()// 设置标题.title( "标题：蚂蚁支付-商户应用API文档" )// 描述.description( "描述：向前端提供商户应用的ResultFul风格接口文档" )// 作者信息.contact( "hubiao" )// 版本.version( "版本号:" + "V1.0.0" ).build();}
}3.生成swagger文档
package com.hubiao.pay.common.merchant.controller;import com.hubiao.pay.merchant.api.MerchantService;
import com.hubiao.pay.merchant.api.dto.MerchantDTO;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RestController;/*** Description** @author hubiao* @since 2020-11-01 21:51*/
@Api(description = "商户平台应用接口")
@RestController
public class MerchantController {@org.apache.dubbo.config.annotation.Referenceprivate MerchantService merchantService;/*** 根据id获取商户信息* @param id* @return*/@ApiOperation( "根据商户id获取商户信息" )@GetMapping("/merchants/{id}")public MerchantDTO queryMerchantById(@PathVariable("id") Long id){return merchantService.queryMerchantById( id );}@ApiOperation( value = "测试swagger其他常用注解",httpMethod = "POST")@PostMapping("/hello")@ApiImplicitParam(name = "id", value = "商户id", dataType = "Long", paramType ="query", required = true)public String hello(Long id){return "hello "+ merchantService.queryMerchantById( id ).getMerchantName();}}
4.使用swagger请求接口测试
- 点击try it out(试一试）
2.输入参数，点击提交请求
3.各种返回参数介绍
5.swagger常用注解
在类中添加swagger注解即可生成swagger接口文档，常用注解如下
@Api：修饰整个类,描述的是controller的作用，写在类的名称上面；
@Api(value = "/merchant", description = "商户管理")
| 属性名称 | 备注 |
|---|---|
| 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 | 高级特性认证时配置 |
@ApiOperation：修饰类的一个方法，用来描述该方法的作用，写在方法上；
@ApiOperation(value = "商户新增", httpMethod = "POST")
| 属性名称 | 备注 |
|---|---|
| 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<Merchant> merchantAdd(@RequestBody @ApiParam(value = "Merchant", required = true) Merchant merchant)
| 属性名称 | 备注 |
|---|---|
| name | 属性名称 |
| value | 属性值 |
| defaultValue | 默认属性值 |
| allowableValues | 可以不配置 |
| required | 是否属性必填 |
| access | 不过多描述 |
| allowMultiple | 默认为false |
| hidden | 隐藏该属性 |
| example | 举例子 |
@ApiModelProperty：用对象接受参数时，用来描述对象中一个字段的作用
@ApiModelProperty("名称")
private String name;
@ ApiResponses :HTTP响应整体的描述，响应集配置
@ApiResponses({ @ApiResponse(code = 400, message = "无效得商户") })
@ ApiResponse :HTTP响应其中一个的描述， 响应集配置
@ApiResponse(code = 400, message = "提供无效得用户")
| 属性名称 | 备注 |
|---|---|
| code | http的状态码 |
| message | 描述 |
| response | 默认响应类 Void |
| reference | 参考ApiOperation中配置 |
| responseHeaders | 参考 ResponseHeader 属性配置说明 |
| responseContainer | 参考ApiOperation中配置 |
@ApiImplicitParams：用在方法上包含一组参数说明；
@ApiImplicitParams({@ApiImplicitParam(name = "id", value = "商户id", dataType = "Long", required = true, paramType = "query"),@ApiImplicitParam(name = "name", value = "商户名称", dataType = "string", paramType = "query", required = true)})
@ApiImplicitParam：用在方法上包含一个参数说明；
@ApiImplicitParam(name = "id", value = "商户id", dataType = "Long", required = true, paramType = "query")
| 属性名称 | 备注 |
|---|---|
| paramType | 参数放在哪个地方 |
| name | 参数代表的含义 |
| value | 参数名称 |
| dataType | 参数类型，有String/Long… |
| required | 是否必填 |
| defaultValue | 参数的默认值 |
swagger配置及注解详解相关推荐
- Spring零配置之@Configuration注解详解
转载自 Spring零配置之@Configuration注解详解 @Configuration介绍 Spring3.0之前要使用Spring必须要有一个xml配置文件,这也是Spring的核心文件,而 ...
- 26.SpringBoot事务注解详解
转自:https://www.cnblogs.com/kesimin/p/9546225.html @Transactional spring 事务注解 1.简单开启事务管理 @EnableTrans ...
- mybatis注解详解
mybatis注解详解 首 先当然得下载mybatis-3.0.5.jar和mybatis-spring-1.0.1.jar两个JAR包,并放在WEB-INF的lib目录下 (如果你使用maven,则 ...
- 开启注解缓存_Spring Boot 2.x基础教程：进程内缓存的使用与Cache注解详解
随着时间的积累,应用的使用用户不断增加,数据规模也越来越大,往往数据库查询操作会成为影响用户使用体验的瓶颈,此时使用缓存往往是解决这一问题非常好的手段之一.Spring 3开始提供了强大的基于注解的缓 ...
- spring-boot注解详解(一)
spring-boot注解详解(一) @SpringBootApplication @SpringBootApplication = (默认属性)@Configuration + @EnableAut ...
- Spring Boot注解详解
文章目录 使用注解的优势 注解详解(配备了完善的释义) 注解列表如下 JPA注解 springMVC相关注解 全局异常处理 项目中具体配置解析和使用环境 使用注解的优势 采用纯java代码,不在需要配 ...
- 【SpringBoot 】SpringBoot注解详解
[SpringBoot ]SpringBoot注解详解 一.注解(annotations)列表 @SpringBootApplication:包含了@ComponentScan.@Configura ...
- java method 注解_JAVA 注解详解及简单实例
JAVA 注解详解及简单实例 何为注解 注解(Annotation)又称为元数据,在JDK1.5后引入,它的作用是: 生成文档 这是注解的原始用途,可以通过注解生成JavaDoc文档 跟踪代码的依赖 ...
- Java基础13：反射与注解详解
Java基础13:反射与注解详解 什么是反射? 反射(Reflection)是Java 程序开发语言的特征之一,它允许运行中的 Java 程序获取自身的信息,并且可以操作类或对象的内部属性. Orac ...
- @Profile注解详解
@Profile注解详解 @Profile: Spring为我们提供的可以根据当前环境,动态的激活和切换一系列组件的功能: 开发环境develop.测试环境test.生产环境master 数据源:(/ ...
最新文章
- 重磅引才！符合条件博士生，给予300平以上别墅一幢！
- java游戏小程序_javaCode 158个经典小程序,里面包含各种小游戏代码，能提高初学者 趣，同事可以从中学习 Games 246万源代码下载- www.pudn.com...
- 震惊，竟然有人用Taro来。。。
- Python-装饰器-案例-获取文件列表
- boost::fibers::buffered_channel的测试程序
- SQL 语句中 where 条件后 写上1=1 是什么意思
- 2017西安交大ACM小学期数据结构 [又是树状数组、异或]
- VBScript基础教程之一什么是 VBScript
- CloudCC:2017年下半年企业移动CRM市场风向窥测
- [转]perl里使用外部命令
- php 内存池,内存详解: 详解PHP内存池中的存储层_php
- python一般的基础代码-Python中的变量，一切代码的基础，你掌握了吗
- Helm 3 完整教程（一）：Helm 3 简介
- tableau货架图制作_举个栗子！Tableau技巧（33）：实用漏斗图的三种制作方法
- NLP--解决Mac OS 10.14.4Python下pip install pyhanlp 失败
- 微信小程序获取用户信息，返回nickName是微信用户，返回了匿名的头像名称原因。
- VisionPro基础篇（一）： VisionPro界面介绍
- 【Java用法】@NotEmpty、@NotBlank、@NotNull注解的使用方法与区别
- mapreduce出现大量task被KILLED_UNCLEAN的3个原因
- web网页短信系统平台后台源码搭建功能篇|移讯云短信系统