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文档的更多相关文章

Spring Boot 入门系列（二十二）使用Swagger2构建 RESTful API文档
前面介绍了如何Spring Boot 快速打造Restful API 接口,也介绍了如何优雅的实现 Api 版本控制,不清楚的可以看我之前的文章:https://www.cnblogs.com/zha ...
Spring Boot中使用Swagger2构建RESTful API文档
在开发rest api的时候,为了减少与其他团队平时开发期间的频繁沟通成本,传统做法我们会创建一份RESTful API文档来记录所有接口细节,然而这样的做法有以下几个问题: 1．由于接口众多,并且细 ...
springboot集成swagger2构建RESTful API文档
在开发过程中,有时候我们需要不停的测试接口,自测,或者交由测试测试接口,我们需要构建一个文档,都是单独写,太麻烦了,现在使用springboot集成swagger2来构建RESTful API文档,可 ...
spring boot / cloud (八) 使用RestTemplate来构建远程调用服务
spring boot / cloud (八) 使用RestTemplate来构建远程调用服务前言上周因家里突发急事,请假一周,故博客没有正常更新 RestTemplate介绍: RestTemp ...
Spring Boot 项目学习 (四) Spring Boot整合Swagger2自动生成API文档
0 引言在做服务端开发的时候,难免会涉及到API 接口文档的编写,可以经历过手写API 文档的过程,就会发现,一个自动生成API文档可以提高多少的效率. 以下列举几个手写API 文档的痛点: 文档需 ...
Spring Boot 集成Swagger2生成RESTful API文档
Swagger2可以在写代码的同时生成对应的RESTful API文档,方便开发人员参考,另外Swagger2也提供了强大的页面测试功能来调试每个RESTful API. 使用Spring Boot可 ...
spring boot 2.x 系列——spring-boot 集成 Swagger2 打造在线接口文档
文章目录一.Springfox 与 Swagger 简介 1.1 Springfox 1.2 Swagger 1.3 OpenApi.Swagger.Springfox的关系二.spring bo ...
Spring Boot中使用Swagger2生成RESTful API文档（转）
效果如下图所示: 添加Swagger2依赖在pom.xml中加入Swagger2的依赖 <!-- https://mvnrepository.com/artifact/io.springfox ...
Spring Boot 系列（七）Swagger2-生成RESTful接口文档
Swagger 是一个规范和完整的框架,用于生成.描述.调用和可视化 RESTful 风格的 Web 服务.总体目标是使客户端和文件系统作为服务器以同样的速度来更新.文件的方法,参数和模型紧密集成到服 ...

随机推荐

代码的坏味道（18）——依恋情结(Feature Envy)
坏味道--依恋情结(Feature Envy) 特征一个函数访问其它对象的数据比访问自己的数据更多. 问题原因这种气味可能发生在字段移动到数据类之后.如果是这种情况,你可能想将数据类的操作移动到这 ...
js回调函数，字符串，数组小析
(一)回调函数:是指通过函数参数传递到其他代码的,某一块可执行代码的引用.这一设计允许了底层代码调用在高层定义的子程序.在抖动函数中,回调函数用于在实现一些功能之后采取的另外的措施,比如div,照片抖 ...
MUI（1）
今天小编用HBuilder+MUI开发移动APP,不用Android原生也不用IOS原生,仅仅用HTML5+MUI.小编也是初学者所以如有不准确的地方望大家指出帮助小编改正,同时也可以促进大家的深入学 ...
MiniDao普通项目集成方案
1.导入必要的jar包: 2.spring配置文件增加如下配置:  <bean id="miniDaoHiberCommonDa ...
easyUI Admin 模板
http://www.oschina.net/p/Easy-Admin?fromerr=23Tfbale
Oracle RAC LoadBalance
LoadBalance 就是把负载平均的分配到集群中的各个节点,从而提高整体的吞吐能力. Oracle 10g RAC 提供了两种不同的方法来分散负载: 通过Connection Balancing, ...
js函数设计原则
一般认为函数指具有返回值的子程序,过程指没有返回值的子程序.C++中把所有子程序成为函数,其实那些返回值为void的函数在语义上也是过程.函数与过程的区别更多是语义上的区别,而不是语法的区别. 语言 ...
setTimeout 虚假的“异步”
看这篇http://www.laruence.com/2009/09/23/1089.html 所以实际上 setTimeout更像是任务按照队列执行经过setTimeout设置后任务放在了队尾 ...
从键盘或文件中获取标准输入：read命令
文件的描述符和重定向文件描述符是和文件的输入.输出相关联的非负整数,Linux内核(kernel)利用文件描述符(file descriptor)来访问文件.打开现存文件或新建文件时,内核会返回一个 ...
Hive管理表，外部表及外部分区表的深入探讨
Hive管理表,也叫内部表.Hive控制着管理表的整个生命周期,默认情况下Hive管理表的数据存放在hive的主目录:/user/hive/warehouse/下,并且当我们删除一张表时,这张表的数据 ...

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

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

前言

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

思路

实现

1.pom.xml集成springfox-swagger2

2.创建Swagger2Config类

3.配置Bean

4.使用@Api来标记controller

5.使用@ApiOperation来标记方法

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

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

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

结束

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

随机推荐

热门专题