API接口文档利器:Swagger
文章目录
- API接口文档利器:Swagger
- Swagger介绍
- Swagger常用注解
- Swagger测试
- Swagger生成API文档的工作原理:
API接口文档利器:Swagger
Swagger介绍
Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务
官网地址 :https://swagger.io/
它的主要作用是:
- 使得前后端分离开发更加方便,有利于团队协作
- 接口的文档在线自动生成,降低后端开发人员编写接口文档的负担
- 功能测试
Spring已经将Swagger纳入自身的标准,建立了Spring-swagger项目,现在叫Springfox。通过在项目中引入
Springfox ,即可非常简单快捷的使用Swagger
SpringBoot集成Swagger
- 在shanjupay-common项目中添加依赖,只需要在shanjupay-common中进行配置即可,因为其他微服务工
程都直接或间接依赖shanjupay-common。
<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. 在jspringboot工程的confifig包中添加一个Swagger配置类
package cn.yyl.sailing.config;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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;@Configuration
@ConditionalOnProperty(prefix = "swagger",value = {"enable"},havingValue = "true")
@EnableSwagger2
public class SwaggerConfiguration {@Beanpublic Docket buildDocket() {return new Docket(DocumentationType.SWAGGER_2).apiInfo(buildApiInfo()).select()// 要扫描的API(Controller)基础包.apis(RequestHandlerSelectors.basePackage("cn.itcast.sailing.controller")).paths(PathSelectors.any()).build();}/*** @param* @return springfox.documentation.service.ApiInfo* @Title: 构建API基本信息* @methodName: buildApiInfo*/private ApiInfo buildApiInfo() {Contact contact = new Contact("徐帆","","");return new ApiInfoBuilder().title("验证码服务API文档").description("包含验证码、短信api").contact(contact).version("1.0.0").build();}}
添加SpringMVC配置类:WebMvcConfifig,让外部可直接访问Swagger文档
package cn.yyl.sailing.config;import org.springframework.stereotype.Component;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;@Component
public class WebMvcConfig implements WebMvcConfigurer {/*** 添加静态资源文件,外部可以直接访问地址** @param registry*/@Overridepublic void addResourceHandlers(ResourceHandlerRegistry registry) {registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");}
}
Swagger常用注解
在Java类中添加Swagger的注解即可生成Swagger接口文档,常用Swagger注解如下:
@Api:修饰整个类,描述Controller的作用 @ApiOperation:描述一个类的一个方法,或者说一个接口
@ApiParam:单个参数的描述信息
@ApiModel:用对象来接收参数
@ApiModelProperty:用对象接收参数时,描述对象的一个字段
@ApiResponse:HTTP响应其中1个描述
@ApiResponses:HTTP响应整体描述
@ApiIgnore:使用该注解忽略这个API
@ApiError :发生错误返回的信息
@ApiImplicitParam:一个请求参数
@ApiImplicitParams:多个请求参数的描述信息
@ApiImplicitParam属性:
属性 | 取值 | 作用 |
---|---|---|
paramType | 查询参数类型 | |
path | 以地址的形式提交数据 | |
query | 直接跟参数完成自动映射赋值 | |
body | 以流的形式提交 仅支持POST | |
header | 参数在request headers 里边提交 | |
form | 以form表单的形式提交 仅支持POST | |
dataType | 参数的数据类型 只作为标志说明,并没有实际验证 | |
Long | ||
String | ||
name | 接收参数名 | |
value | 接收参数的意义描述 | |
required | 参数是否必填 | |
true | 必填 | |
false | 非必填 | |
defaultValue | 默认值 |
上边的属性后边编写程序时用到哪个我再详细讲解,下边写一个swagger的简单例子,我们在MerchantController 中添加Swagger注解,代码如下所示:
package cn.yyl.sailing.controller;import cn.itcast.sailing.common.domain.RestResponse;
import cn.itcast.sailing.dto.VerificationInfo;
import cn.itcast.sailing.service.VerificationService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;import java.util.Map;@Api(value = "验证码服务接口")
@RestController
public class VerificationController {@Autowiredprivate VerificationService verificationService;/*** 生成手机验证码** @param name 业务名* @param payload 业务携带参数,如手机号 ,邮箱* @param effectiveTime 验证信息有效期(秒)* @return*/@ApiOperation(value = "生成验证信息", notes = "生成验证信息")@ApiImplicitParams({@ApiImplicitParam(name = "name", value = "业务名称", required = true, dataType = "String", paramType = "query"),@ApiImplicitParam(name = "payload", value = "业务携带参数,如手机号 ,邮箱", required = true, paramType = "body"),@ApiImplicitParam(name = "effectiveTime", value = "验证信息有效期(秒)", required = false, dataType = "String", paramType = "query")})@PostMapping(value = "/generate")public RestResponse<VerificationInfo> generateVerificationInfo(@RequestParam("name") String name,@RequestBody Map<String, Object> payload,@RequestParam("effectiveTime") int effectiveTime) {VerificationInfo verificationInfo = verificationService.generateVerificationInfo(name, payload, effectiveTime);return RestResponse.success(verificationInfo);}/**** 校验手机验证码* @param name 业务名称* @param verificationKey 验证key* @param verificationCode 验证码* @return*/@ApiOperation(value = "校验", notes = "校验")@ApiImplicitParams({@ApiImplicitParam(name = "name", value = "业务名称", required = true, dataType = "String", paramType = "query"),@ApiImplicitParam(name = "verificationKey", value = "验证key", required = true, dataType = "String", paramType = "query"),@ApiImplicitParam(name = "verificationCode", value = "验证码", required = true, dataType = "String", paramType = "query")})@PostMapping(value = "/verify")public RestResponse<Boolean> verify(String name, String verificationKey, String verificationCode) {Boolean isSuccess = verificationService.verify(name, verificationKey, verificationCode);return RestResponse.success(isSuccess);}@ApiOperation("测试")@GetMapping(path = "/hello")public String hello() {return "hello";}@ApiOperation("测试")@ApiImplicitParam(name = "name", value = "姓名", required = true, dataType = "string")@PostMapping(value = "/hi")public String hi(String name) {return "hi," + name;}
}
Swagger测试
启动商户应用和商户中心服务,访问:http://localhost:57010/你的服务访问地址/swagger-ui.html
服务访问地址在yml配置中:
打开页面如下:
点击其中任意一项即可打开接口详情,如下图所示:
点击“Try it out”开始测试,并录入参数信息,然后点击“Execute"发送请求,执行测试返回结果:“hi,李四”
Swagger生成API文档的工作原理:
1、springboot项目启动时会扫描到SwaggerConfiguration类
2、在此类中指定了扫描包路径com.包名.controller,会找到在此包下及子包下标记有 @RestController注解的controller类
3、根据controller类中的Swagger注解生成API文档
API接口文档利器:Swagger相关推荐
- php怎么根据接口文档实现功能,CodeIgniter+swagger实现 PHP API接口文档自动生成功能...
一.安装swagger 1.首先需要有composer,没有的自行百度安装 2.下载swagger,打开网站https://packagist.org/packages/zircote/swagger ...
- Spring Boot API 接口文档 Swagger 入门
转载自 芋道 Spring Boot API 接口文档 Swagger 入门 摘要: 原创出处 http://www.iocoder.cn/Spring-Boot/Swagger/ 「芋道源码」欢迎转 ...
- Swagger 生成 PHP API 接口文档
Swagger 生成 PHP API 接口文档 标签(空格分隔): php 1.概况 有同学反馈写几十个接口文档需要两天的工作量, 随着多部门之间的协作越来越频繁, 维护成本越来越高, 文档的可维护性 ...
- Laravel使用swagger PHP生成api接口文档
Laravel使用swagger PHP生成api接口文档 Swagger集接口文档和测试于一体,就类比将postman和showdoc的结合体 首先要先安装基于laravel5的swagger包 地 ...
- 芋道 Spring Boot API 接口文档 Swagger 入门
点击上方"芋道源码",选择"设为星标" 做积极的人,而不是积极废人! 源码精品专栏 原创 | Java 2020 超神之路,很肝~ 中文详细注释的开源项目 RP ...
- swagger php 生成api,blog/Swagger生成php restful API接口文档.md at master · lfq618/blog · GitHub...
Swagger生成php restful API接口文档 背景 我们的restful api项目采用yaf框架, 整体结构简单, 我们只需要用swagger扫描 application目录即可. 下面 ...
- 整合swagger2生成Restful Api接口文档
整合swagger2生成Restful Api接口文档 swagger Restful文档生成工具 2017-9-30 官方地址:https://swagger.io/docs/specificati ...
- echarts4离线使用文档_适合写API接口文档的管理工具有哪些?
现在越来越流行前后端分离开发,使用ajax交互.所以api接口文档就变的十分有意义了,目前市场有哪些比较优秀的接口文档管理工具呢? 1.MinDoc 网址:https://www.iminho.me/ ...
- 接口文档神器Swagger(下篇)
本文来自网易云社区 作者:李哲 二.Swagger-springmvc原理解析 上面介绍了如何将springmvc和springboot与swagger结合,通过简单配置生成接口文档,以及介绍了swa ...
最新文章
- 业界首个面向NLP场景深度迁移学习框架
- kvm虚拟化学习笔记(十一)之kvm虚拟机扩展磁盘空间
- C#winform实现鼠标响应左键按下,并记下其坐标
- 3、Python 基础类型 -- List 列表类型
- javaScript学习笔记之类型转换
- 关于SimpleDateFormat线程不安全的源码分析
- SPOJ 9939 Eliminate the Conflict
- spring boot 处理自定义注解
- jqprint 分页打印_JS实现页面打印(整体、局部)
- 二:C#对象、集合、DataTable与Json内容互转示例;
- python第五章课后答案汉诺塔_用python编写一个程序,得到汉诺塔的解决方案
- remapkey不能打开注册表_卸载 AutoCAD 清理注册表
- 左右极限相等的matlab,如何求左右极限
- Hilbert变换器
- 分布式对象存储oss-minio
- Word错别字校对-JCJC
- 南水北调中线调水量仅占丹江口水库水量1/4
- jet-cp4005,linux双面打印,HP LaserJet Pro M706n 双面打印 技术规格 | HP®People's Republic of China...
- 渗透tools之Lizard
- 从零开始配置 react + typescript(三):webpack