SpringBoot开发案例之整合Swagger篇

zhifuAPI.png

前段时间整合过的一个支付服务,由于使用了Spring Boot快速开发,但是又懒得写详细的文档介绍,便顺手就把Swagger整合进来了,对支付服务进行分组API展示,如上图。

简介

Swagger 是一个规范和完整的框架,用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新 。接口的方法,参数和模型紧密集成到服务器端的代码,允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

在实际开发过程中,我们的RESTful API就有可能要面对多个开发人员或多个开发团队:IOS开发、Android开发、Web开发等。为了减少与其他团队平时开发期间的频繁沟通成本,传统做法我们会创建一份RESTful API文档来记录所有接口细节,然而这样的做法有以下几个问题:

  • 由于接口众多,并且细节复杂(需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等),高质量地创建这份文档本身就是件非常吃力的事,下游的抱怨声不绝于耳
  • 随着时间推移,不断修改接口实现的时候都必须同步修改接口文档,而文档与代码又处于两个不同的媒介,除非有严格的管理机制,不然很容易导致不一致现象

而swagger完美的解决了上面的几个问题,并与Spring boot程序配合组织出强大RESTful API文档。它既可以减少我们创建文档的工作量,同时说明内容又整合入实现代码中,让维护文档和修改代码整合为一体,可以让我们在修改代码逻辑的同时方便的修改文档说明。另外Swagger2也提供了强大的页面测试功能 来调试每个RESTful API。

添加Swagger2依赖

<!-- swagger2 文档 截止目前 为最新版本 -->
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.7.0</version>
</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.7.0</version>
</dependency>

创建Swagger2配置类

在Application.java同级包下创建Swagger2的配置类。

@Configuration //让Spring来加载该类配置
@EnableSwagger2 //启用Swagger2
public class Swagger2 {
	@Bean
	public Docket alipayApi() {
		return new Docket(DocumentationType.SWAGGER_2)
		        .groupName("支付宝API接口文档")  
		        .apiInfo(apiInfo())
				.select()
				.apis(RequestHandlerSelectors.basePackage("com.itstyle.modules.alipay"))
				.paths(PathSelectors.any()).build();
	}
	@Bean
	public Docket weixinpayApi() {
		return new Docket(DocumentationType.SWAGGER_2)
		        .groupName("微信API接口文档")  
		        .apiInfo(apiInfo())
				.select()
				.apis(RequestHandlerSelectors.basePackage("com.itstyle.modules.weixinpay"))
				.paths(PathSelectors.any()).build();
	}
	@Bean
	public Docket unionpayApi() {
		return new Docket(DocumentationType.SWAGGER_2)
		        .groupName("银联API接口文档")  
		        .apiInfo(apiInfo())
				.select()
				.apis(RequestHandlerSelectors.basePackage("com.itstyle.modules.unionpay"))
				.paths(PathSelectors.any()).build();
	}
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
				.title("支付系统")
				.description("微信、支付宝、银联支付服务")
				.termsOfServiceUrl("http://blog.52itstyle.com")
				.contact(new Contact("科帮网 ", "http://blog.52itstyle.com", "345849402@qq.com"))
				.version("1.0").build();
	}

}

添加API注解

API说明:

/**
  swagger2使用说明:
         @Api:用在类上,说明该类的作用
         @ApiOperation:用在方法上,说明方法的作用
		 @ApiIgnore:使用该注解忽略这个API
         @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的属性
 */

代码实现:

/**
 * 银联支付
 * 创建者 科帮网
 * 创建时间	2017年8月2日
 */
@Api(tags ="银联支付")
@Controller
@RequestMapping(value = "unionpay")
public class UnionPayController {
    private static final Logger logger =    LoggerFactory.getLogger(AliPayController.class);

    @Autowired
    private IUnionPayService unionPayService;

@ApiOperation(value="银联支付主页")   @RequestMapping(value="index",method=RequestMethod.GET)
    public String   index() {
        return "unionpay/index";
    }

@ApiOperation(value="电脑支付")	
@RequestMapping(value="pcPay",method=RequestMethod.POST)
@ApiImplicitParam(name = "product", value = "产品信息", required = true, dataType = "Product")
   public String  pcPay(Product product,ModelMap map) {
		logger.info("电脑支付");
		product.setPayWay(PayWay.PC.getCode());
		String form  =  unionPayService.unionPay(product);
		map.addAttribute("form", form);
		return "unionpay/pay";
    }
@ApiIgnore//使用该注解忽略这个API
@ApiOperation(value="手机H5支付")
@RequestMapping(value="mobilePay",method=RequestMethod.POST)
    public String  mobilePay(Product product,ModelMap map) {
		logger.info("手机H5支付");
		product.setPayWay(PayWay.MOBILE.getCode());
		String form  =  unionPayService.unionPay(product);
		map.addAttribute("form", form);
		return "unionpay/pay";
    }
}

访问

配置完成后,我们重启服务,访问地址 http://localhost:8080/项目名/swagger-ui.html,如:

http://localhost:8080/springboot_pay/swagger-ui.html

完整项目案例可查看 支付服务

原创声明,本文系作者授权云+社区发表,未经许可,不得转载。

如有侵权,请联系 yunjia_community@tencent.com 删除。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏刘君君

Spring Boot中使用Swagger2构建强大的RESTful API文档

3437
来自专栏史上最简单的Spring Cloud教程

SpringBoot非官方教程 | 第十一篇:springboot集成swagger2,构建优雅的Restful API

swagger,中文“拽”的意思。它是一个功能强大的api框架,它的集成非常简单,不仅提供了在线文档的查阅,而且还提供了在线文档的测试。另外swagger很容易...

2598
来自专栏菩提树下的杨过

mac 10.9.4下配置apache

启动后,访问 http://localhost/ 应该能看到"It works!"的初始页面,如果对初始页面的内容感到好奇,可以打开"/etc/apache2/...

762
来自专栏LanceToBigData

SpirngBoot之整合Swagger2

swagger,中文“拽”的意思。它是一个功能强大的api框架,它的集成非常简单,不仅提供了在线文档的查阅, 而且还提供了在线文档的测试。另外swagger很...

851
来自专栏carven

实习笔记2--20160121

860
来自专栏Albert陈凯

2018-11-18 swagger2 自动生成API

作者:小莫 链接:https://www.zhihu.com/question/28119576/answer/134580038 来源:知乎 著作权归作...

2573
来自专栏xingoo, 一个梦想做发明家的程序员

Linux下Apache服务器使用入门----.htaccess

这个文件的作用就是,把它放在某个目录下面,它所修改的配置方案会应用到这个目录,及其子目录 开启方式: 在/etc/httpd/conf/httpd.conf文件...

2038
来自专栏battcn

一起来学SpringBoot | 第十一篇:集成Swagger在线调试

随着互联网技术的发展,现在的网站架构基本都由原来的后端渲染,变成了:前端渲染、前后端分离的形态,而且前端和后端在各自的技术道路上越走越远。

1073
来自专栏专注于主流技术和业务

REST API文档工具Swagger2,以及与SpringBoot的集成

swagger是一个API框架,号称世界上最流行的API工具。它提供了API管理的全套解决方案,比如API在线编辑器,APIUI展示界面,代码生成器等诸多功能。...

1062
来自专栏乐沙弥的世界

Apache httpd 2.4 alias 别名配置

Web网站别名配置是被经常使用的一个特性。这个功能实际上是为站点URI定义一个路径映射关系,其配置和使用也较为简单。以下是基于CentOS 7下实现alias的...

861

扫码关注云+社区

领取腾讯云代金券