spring cloud 学习(10) - 利用springfox集成swagger

对绝大多数程序员而言,写接口文档是一件痛苦的事情,相对文档,他们更愿意写代码。最理想的情况就是:代码即文档!服务开发完成后,部署上去文档就自动生成,没错,这就是springfox + swagger要解决的问题!

swagger号称 THE WORLD'S MOST POPULAR API TOOLING。但swagger默认情况下,仍要单独部署,程序员还是要跑到一个单独的web页面上编辑,写一堆yaml文档,依然不爽。

github上有一个springfox项目,可以在开发rest服务时,只要加一些注解,就自动生成swagger-ui界面,以及相关的文档,而且可以跟spring-boot/spring-cloud无缝集成。

步骤:

一、添加依赖项

    dependencies {
        ...
        compile "io.springfox:springfox-swagger2:2.7.0"
        compile "io.springfox:springfox-swagger-ui:2.7.0"
        ...
    }

二、添加swagger配置类

 1 package cn.mwee.order.cloud.service.express.config;
 2 
 3 import org.springframework.context.annotation.Bean;
 4 import org.springframework.context.annotation.Configuration;
 5 import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
 6 import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter;
 7 import springfox.documentation.builders.ApiInfoBuilder;
 8 import springfox.documentation.builders.PathSelectors;
 9 import springfox.documentation.builders.RequestHandlerSelectors;
10 import springfox.documentation.service.ApiInfo;
11 import springfox.documentation.service.Contact;
12 import springfox.documentation.spi.DocumentationType;
13 import springfox.documentation.spring.web.plugins.Docket;
14 import springfox.documentation.swagger2.annotations.EnableSwagger2;
15 
16 /**
17  * Created by yangjunming on 13/10/2017.
18  */
19 @Configuration
20 @EnableSwagger2
21 public class SwaggerConfig {
22 
23     @Bean
24     public Docket createRestApi() {
25         return new Docket(DocumentationType.SWAGGER_2)
26                 .apiInfo(apiInfo())
27                 .select()
28                 .apis(RequestHandlerSelectors.basePackage("xxx.controller")) //Controller所在的package
29                 .paths(PathSelectors.any())
30                 .build();
31     }
32 
33     @Bean
34     public WebMvcConfigurerAdapter addResourceHandlers() {
35         return new WebMvcConfigurerAdapter() {
36             @Override
37             public void addResourceHandlers(ResourceHandlerRegistry registry) {
38                 registry.addResourceHandler("swagger-ui.html")
39                         .addResourceLocations("classpath:/META-INF/resources/");
40                 registry.addResourceHandler("/webjars/**")
41                         .addResourceLocations("classpath:/META-INF/resources/webjars/");
42             }
43         };
44     }
45 
46     private ApiInfo apiInfo() {
47         return new ApiInfoBuilder()
48                 .title("express-service online api document")
49                 .description("某某服务") 
50                 .contact(new Contact("作者名字", "http://作者介绍网址", "作者@邮箱.com"))
51                 .version("1.0.0") //显示版本号
52                 .build();
53     }
54 }

三、在Controller上添加注解

 1 package cn.mwee.order.cloud.service.express.controller;
 2 
 3 import cn.mwee.order.cloud.admin.common.controller.AbstractController;
 4 import cn.mwee.order.cloud.admin.service.dto.common.DataResult;
 5 import cn.mwee.order.cloud.admin.service.dto.express.sf.*;
 6 import cn.mwee.order.cloud.admin.service.express.SFExpressService;
 7 import io.swagger.annotations.Api;
 8 import io.swagger.annotations.ApiOperation;
 9 import org.springframework.beans.factory.annotation.Autowired;
10 import org.springframework.cloud.context.config.annotation.RefreshScope;
11 import org.springframework.web.bind.annotation.PostMapping;
12 import org.springframework.web.bind.annotation.RequestBody;
13 import org.springframework.web.bind.annotation.RequestMapping;
14 import org.springframework.web.bind.annotation.RestController;
15 
16 import javax.servlet.http.HttpServletRequest;
17 
18 /**
19  * Created by 菩提树下的杨过(http://yjmyzz.cnblogs.com/) on 2017/7/18.
20  */
21 @RestController
22 @RefreshScope
23 @RequestMapping("/sf")
24 @Api(consumes = "application/json",
25         produces = "application/json",
26         protocols = "http",
27         basePath = "/sf", value = "顺丰对接服务")
28 public class SFController extends AbstractController {
29 
30     ...
31 
32     @ApiOperation(value = "下单", tags = "顺丰速运")
33     @PostMapping(value = "submitOrder")
34     public DataResult<SFSubmitResponse> submitOrder(@RequestBody SFSubmitOrderRequest request) throws Exception {
35         return ...;
36     }
37 
38     ...
39 
40 }

注意上面几处带@Api开头的注解

四、参数实体上添加注解

 1 package cn.mwee.order.cloud.admin.service.dto.express.sf;
 2 
 3 import cn.mwee.order.cloud.admin.service.dto.express.ExpressBaseOrder;
 4 import cn.mwee.order.common.utils.date.DateUtil;
 5 import com.alibaba.fastjson.annotation.JSONField;
 6 import io.swagger.annotations.ApiModel;
 7 import io.swagger.annotations.ApiModelProperty;
 8 import lombok.Data;
 9 import lombok.EqualsAndHashCode;
10 
11 import java.util.ArrayList;
12 import java.util.Date;
13 import java.util.List;
14 
15 /**
16  * 顺丰的物流订单
17  * Created by 菩提树下的杨过(http://yjmyzz.cnblogs.com/) on 26/09/2017.
18  */
19 @Data
20 @EqualsAndHashCode(callSuper = false)
21 @ApiModel(description = "顺丰-提交订单参数")
22 public class SFSubmitOrderRequest extends ExpressBaseOrder {
23 
24     @ApiModelProperty(value = "商家编码(顺丰分配提供)", required = true, dataType = "String", example = "A001")
25     private String clientCode; //商家编码,为顺丰分配提供
26 
27     ...
28 }

还是注意上面几处带@Api开头的注解,一看就懂。

启动后,就可以用 http://xxxx.xxxx:port/swagger-ui.html访问了

随便点开一个方法,比如cancelOrder

还可以直接调用REST(相当于postman之类的rest服务测试工具了)

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏bboysoul

使用永恒之蓝(MS17-010)漏洞入侵windows7

前几天,被勒索病毒(Wannacry)刷屏了,这个病毒是大家知道了备份文件的重要性,当然,我是不怕什么病毒的,因为我是一天备份一次文件,而且微云一份,坚果云,移...

3.2K40
来自专栏Android先生

【漫画技术】Android跨进程通信

Tips:4个环节,共计约9小时的精心打磨完成上线,同时也非常感谢参与审稿的同学。

12320
来自专栏程序员与猫

Log system architecture

Keywords: Collector, Processor, Aggregator

19610
来自专栏java达人

SpringMVC下Excel文件的上传下载

在实际应用中,经常会遇到上传Excel或者下载Excel的情况,比如导入数据、下载统计数据等等场景。针对这个问题,我写了个基于SpringMVC的简单上传下载示...

35190
来自专栏乐沙弥的世界

X86 DBCA, NETCA GIVE JAVA HOTSPOT ERROR IF ON X86_64 HARDWARE

    在使用DBCA命令创建新的数据库时,DBCA命令无法启动。运行的环境是宿主机64bit+AMD cpu, 而客户机为Linux 32bit + Grid...

10420
来自专栏数据库新发现

Use EMC powermt to solve PowerPath Problem

http://www.eygle.com/unix/Use.EMC.Powermt.Solve.Config.Problem.htm

15030
来自专栏Hongten

php开发_php环境搭建

学php开发,首先是要把环境给搭建起来,然后再写出自己的第一个"helloworld"小程序。

37020
来自专栏Netkiller

怎样制作RPM包

怎样制作RPM包 摘要 我在网上找RPM包的制作例子几乎都是C源码编译安装然后生成RPM包, 而我的程序不是C写的很多时候是脚本语言如Python, PHP 甚...

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

CQRS框架:AxonFramework 之 Hello World

Command Query Responsibility Segregation,CQRS 这个架构好象最近博客园里讨论得比较多,有几篇园友的文章很有深度,推荐...

49870
来自专栏Objective-C

iOS-安装和使用 CocoaPods

55770

扫码关注云+社区

领取腾讯云代金券