文档章节

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

wangkang80
 wangkang80
发布于 2017/05/26 11:14
字数 577
阅读 851
收藏 7

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("com.egridcloud")).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这个组件,目前看下来就是对业务代码有一定的入侵,总之使用前请根据自身项目情况做好评估,不要盲目跟风.


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

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

© 著作权归作者所有

wangkang80
粉丝 365
博文 22
码字总数 34117
作品 3
浦东
高级程序员
私信 提问
加载中

评论(2)

qwfys
qwfys
另外,现在也已经有了一个关于swagger的spring-boot插件,在maven中添加就可以了。
qwfys
qwfys
markdown语法中,#和后面的标题之间加一个空格,这样标题就可以被markdown注释器识别了。
Swagger2与Spring REST Docs

编者注 之前让其他写服务端的小伙伴支持swagger,然后最近一直在写Unity,没有把之前的项目和Swagger进行集成 Swagger Core Swagger Core Git Swagger 2.X 快速开始 注意:Swagger 2.x 遵循O...

抢小孩糖吃
02/21
0
0
UDF 集成样例--udf-sample

UDF 基于spring boot / spring cloud 的基础项目,脚手架,主要用于学习和实践 按照spring boot的思想,将各个不同的功能按照starter的形式拆分开来,做到灵活组合 物理架构示意 CI & CD 示意 代...

wangkang80
2017/08/27
344
0
spring boot 1.5.4 集成Swagger2构建Restful API(十八)

上一篇博客地址:springboot 1.5.4 整合rabbitMQ(十七) 1 Spring Boot集成Swagger2构建RESTful API文档 1.1 Swagger2简介 Swagger2官网:http://swagger.io/ 由于Spring Boot能够快速开发、...

wyait
2017/11/03
0
0
SpringMVC集成springfox-swagger2构建restful API

在集成springfox-swagger2之前,我也尝试着集成了swagger-springmvc,方式差不多,但是swagger-springmvc相对麻烦一点,因为要把它的静态文件copy到自己的项目中。所以还是用新版本的。 至于...

u014231523
2017/01/13
0
0
白话SpringCloud | 第十一章:路由网关(Zuul):利用swagger2聚合API文档

前言 通过之前的两篇文章,可以简单的搭建一个路由网关了。而我们知道,现在都奉行开发,前后端开发的沟通成本就增加了,所以一般上我们都是通过进行api文档生成的。现在由于使用了统一路由网...

oKong
2018/10/20
0
0

没有更多内容

加载失败,请刷新页面

加载更多

偶遇 JDK 1.8 还未修复的 SecureRandom.getInstance("SHA1PRNG") 之 bug

楼主今天兴高采烈的在部署环境,下载 JDK,打包项目,上传至服务器。 配置 JDK ,打包上传项目楼主就不在这里重复了,读者自行解决哈! 1. 启动项目 java -jar xxxx.jar 令楼主没有想到的是:...

Ryan-瑞恩
22分钟前
8
0
【更新】Stimulsoft Reports v2019.3.1发布,新增对OData v4的支持功能

下载Stimulsoft Report.Ultimate v2019.3.1试用版 集所有报表解决方案于一体的综合性平台 Stimulsoft Reports.Ultimate是集所有报表解决方案于一体的综合性平台,拥有在JavaScript、ASP.NET...

xiaochuachua
22分钟前
1
0
JVM源码分析之javaagent原理完全解读

JVM源码分析之javaagent原理完全解读 概述 本文重点讲述javaagent的具体实现,因为它面向的是我们Java程序员,而且agent都是用Java编写的,不需要太多的C/C++编程基础,不过这篇文章里也会讲...

BryceLoski
28分钟前
1
0
git记住密码

git取消记住密码 git config --system --unset credential.helper git记住密码 git config --global credential.helper store...

大灰狼wow
29分钟前
2
0
java 面试知识点笔记(十四)异常体系

问:Error和Exception的区别? ps:Throwable上层是Object Error:程序无法处理的系统错误,编译器不做检查 Exception:程序可以处理的异常,捕获后可能恢复 RuntimeException:不可预知的,...

断风格男丶
32分钟前
1
0

没有更多内容

加载失败,请刷新页面

加载更多

返回顶部
顶部