spring boot / cloud (三) 集成springfox-swagger2构建在线API文档

前言

不能同步更新API文档会有什么问题?

理想情况下,为所开发的服务编写接口文档,能提高与周边系统对接联调的效率.但前提条件是,服务和API文档必须是同步更新的,如果不能保证同步,那接口文档就会流于形式,不仅不能起到应有的作用,甚至某些情况下,甚至会误导对接的系统,导致更低效率的沟通.

思路

  • 根据现有的服务定义来自动生成接口文档

实现

1.pom.xml集成springfox-swagger2

	<!-- swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${springfox-swagger2.version}</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${springfox-swagger2.version}</version>
</dependency>

2.创建Swagger2Config类

@Configuration
@EnableSwagger2
public class Swagger2Config { }

3.配置Bean

  @Bean
public WebMvcConfigurerAdapter addResourceHandlers() {
return new WebMvcConfigurerAdapter() {
@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
registry.addResourceHandler("swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
};
}

注意点 : 版本号和项目名称可在配置文件中定义(从pom中取)

 @Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).select()
.apis(RequestHandlerSelectors.basePackage("org.itkk")).paths(PathSelectors.any())
.build();
} private ApiInfo apiInfo() {
ApiInfoBuilder apiInfoBuilder = new ApiInfoBuilder();
apiInfoBuilder.title(this.projectName + " online api document");
apiInfoBuilder.version(version);
return apiInfoBuilder.build();
}

4.使用@Api来标记controller

@RestController
@RequestMapping("demo")
@Api(value = "demo",
consumes = "application/json",
produces = "application/json",
protocols = "http")
public class DemoController { }

5.使用@ApiOperation来标记方法

  @ApiOperation(value = "add", notes = "add")
@RequestMapping(value = "add", method = RequestMethod.GET)
public RestResponse<Integer> add(Integer a, Integer b) {
return new RestResponse<>(demoService.add(a, b));
}

6.使用@ApiImplicitParams和@ApiImplicitParam来标参数

  @ApiOperation(value = "add", notes = "add")
@ApiImplicitParams({
@ApiImplicitParam(paramType = "query", name = "a", value = "a", required = true,
dataType = "int"),
@ApiImplicitParam(paramType = "query", name = "b", value = "a", required = true,
dataType = "int") })
@RequestMapping(value = "add", method = RequestMethod.GET)
public RestResponse<Integer> add(Integer a, Integer b) {
return new RestResponse<>(demoService.add(a, b));
}

7.使用@ApiModel和@ApiModelProperty来标实体类

@ApiModel(description = "响应消息体")
public class RestResponse<T> implements Serializable { /**
*
* 描述 : id
*
*/
private static final long serialVersionUID = 1L; /**
* 描述 : 响应ID
*/
@ApiModelProperty(value = "响应ID", required = true, dataType = "string")
private String id = UUID.randomUUID().toString(); ............. }

代码仓库 (博客配套代码)

结束

以上配置结束之后,启动项目,访问http://xxxxx/swagger-ui.html即可能够访问接口文档,并且直接可以做接口调用测试.

然后对于Swagger2这个组件,目前看下来就是对业务代码有一定的入侵,总之使用前请根据自身项目情况做好评估,不要盲目跟风.


想获得最快更新,请关注公众号

spring boot / cloud (三) 集成springfox-swagger2构建在线API文档的更多相关文章

  1. Spring Boot 入门系列(二十二)使用Swagger2构建 RESTful API文档

    前面介绍了如何Spring Boot 快速打造Restful API 接口,也介绍了如何优雅的实现 Api 版本控制,不清楚的可以看我之前的文章:https://www.cnblogs.com/zha ...

  2. Spring Boot中使用Swagger2构建RESTful API文档

    在开发rest api的时候,为了减少与其他团队平时开发期间的频繁沟通成本,传统做法我们会创建一份RESTful API文档来记录所有接口细节,然而这样的做法有以下几个问题: 1.由于接口众多,并且细 ...

  3. springboot集成swagger2构建RESTful API文档

    在开发过程中,有时候我们需要不停的测试接口,自测,或者交由测试测试接口,我们需要构建一个文档,都是单独写,太麻烦了,现在使用springboot集成swagger2来构建RESTful API文档,可 ...

  4. spring boot / cloud (八) 使用RestTemplate来构建远程调用服务

    spring boot / cloud (八) 使用RestTemplate来构建远程调用服务 前言 上周因家里突发急事,请假一周,故博客没有正常更新 RestTemplate介绍: RestTemp ...

  5. Spring Boot 项目学习 (四) Spring Boot整合Swagger2自动生成API文档

    0 引言 在做服务端开发的时候,难免会涉及到API 接口文档的编写,可以经历过手写API 文档的过程,就会发现,一个自动生成API文档可以提高多少的效率. 以下列举几个手写API 文档的痛点: 文档需 ...

  6. Spring Boot 集成Swagger2生成RESTful API文档

    Swagger2可以在写代码的同时生成对应的RESTful API文档,方便开发人员参考,另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API. 使用Spring Boot可 ...

  7. spring boot 2.x 系列——spring-boot 集成 Swagger2 打造在线接口文档

    文章目录 一.Springfox 与 Swagger 简介 1.1 Springfox 1.2 Swagger 1.3 OpenApi.Swagger.Springfox的关系 二.spring bo ...

  8. Spring Boot中使用Swagger2生成RESTful API文档(转)

    效果如下图所示: 添加Swagger2依赖 在pom.xml中加入Swagger2的依赖 <!-- https://mvnrepository.com/artifact/io.springfox ...

  9. Spring Boot 系列(七)Swagger2-生成RESTful接口文档

    Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.总体目标是使客户端和文件系统作为服务器以同样的速度来更新.文件的方法,参数和模型紧密集成到服 ...

随机推荐

  1. 代码的坏味道(18)——依恋情结(Feature Envy)

    坏味道--依恋情结(Feature Envy) 特征 一个函数访问其它对象的数据比访问自己的数据更多. 问题原因 这种气味可能发生在字段移动到数据类之后.如果是这种情况,你可能想将数据类的操作移动到这 ...

  2. js回调函数,字符串,数组小析

    (一)回调函数:是指通过函数参数传递到其他代码的,某一块可执行代码的引用.这一设计允许了底层代码调用在高层定义的子程序.在抖动函数中,回调函数用于在实现一些功能之后采取的另外的措施,比如div,照片抖 ...

  3. MUI(1)

    今天小编用HBuilder+MUI开发移动APP,不用Android原生也不用IOS原生,仅仅用HTML5+MUI.小编也是初学者所以如有不准确的地方望大家指出帮助小编改正,同时也可以促进大家的深入学 ...

  4. MiniDao普通项目集成方案

    1.导入必要的jar包: 2.spring配置文件增加如下配置: <!-- Hibernate工具栏配置--> <bean id="miniDaoHiberCommonDa ...

  5. easyUI Admin 模板

    http://www.oschina.net/p/Easy-Admin?fromerr=23Tfbale

  6. Oracle RAC LoadBalance

    LoadBalance 就是把负载平均的分配到集群中的各个节点,从而提高整体的吞吐能力. Oracle 10g RAC 提供了两种不同的方法来分散负载: 通过Connection Balancing, ...

  7. js函数设计原则

    一般认为函数指具有返回值的子程序,过程指没有返回值的子程序.C++中把所有子程序成为函数,其实那些返回值为void的 函数在语义上也是过程.函数与过程的区别更多是语义上的区别,而不是语法的区别. 语言 ...

  8. setTimeout 虚假的“异步”

    看这篇http://www.laruence.com/2009/09/23/1089.html 所以实际上 setTimeout更像是任务按照队列执行  经过setTimeout设置后任务放在了队尾 ...

  9. 从键盘或文件中获取标准输入:read命令

    文件的描述符和重定向 文件描述符是和文件的输入.输出相关联的非负整数,Linux内核(kernel)利用文件描述符(file descriptor)来访问文件.打开现存文件或新建文件时,内核会返回一个 ...

  10. Hive管理表,外部表及外部分区表的深入探讨

    Hive管理表,也叫内部表.Hive控制着管理表的整个生命周期,默认情况下Hive管理表的数据存放在hive的主目录:/user/hive/warehouse/下,并且当我们删除一张表时,这张表的数据 ...