《Spring Boot极简教程》第14章 Spring Boot集成Swagger2构建自动化Rest API文档-阿里云开发者社区

开发者社区> 程序员诗人> 正文

《Spring Boot极简教程》第14章 Spring Boot集成Swagger2构建自动化Rest API文档

简介: 第14章 Spring Boot集成Swagger2构建自动化Rest API文档 Swagger2的API文档 在以往的项目中,关于API接口文档,我们一般使用wiki或者干脆就是“线下文档”。
+关注继续查看

第14章 Spring Boot集成Swagger2构建自动化Rest API文档

Swagger2的API文档

在以往的项目中,关于API接口文档,我们一般使用wiki或者干脆就是“线下文档”。缺点是很明显的:在迭代开发过程中,API会频繁变动,这样文档需要同步修改。繁琐。如果不及时更新,就会出生调用方没有及时了解到API签名的变化,导致较大的沟通很改动成本。

微服务时代,效率第一。

使用Swagger可以在部署的时候,实时生成最新的在线API文档,而且不仅仅是文档,同时支持API接口的测试。

我们使用Swagger,只需要在我们的开发代码中,加上少量的注解配置,即可 自动化构建Rest API文档。在多人协作的开发过程中,API文档不仅可以减少等待,也能保证开发的持续进行。有一些单元测试框架可以生成API文档,而Swagger可以在不写单元测试的情况下生成在线的API页面,并且可以直接在页面进行API调试。

SpringBoot集成Swagger2步骤

1.添加工程依赖的jar

在build.gradle中添加swagger2的依赖:

    // https://mvnrepository.com/artifact/io.springfox/springfox-swagger2
    compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.6.1'
   // https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui
    compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.6.1'

完整的build.gradle配置如下:

group 'com.easy.springboot'
version '1.0-SNAPSHOT'

apply plugin: 'groovy'
apply plugin: 'java'
apply plugin: 'org.springframework.boot'

sourceCompatibility = 1.8

repositories {
//    mavenCentral()
//    jcenter()
    maven {
        url 'http://maven.aliyun.com/nexus/content/groups/public/'
    }

}

dependencies {
    compile 'org.codehaus.groovy:groovy-all:2.3.11'
    testCompile group: 'junit', name: 'junit', version: '4.12'

    compile('org.springframework.boot:spring-boot-starter-web')
    
    // https://mvnrepository.com/artifact/io.springfox/springfox-swagger2
    compile group: 'io.springfox', name: 'springfox-swagger2', version: '2.6.1'
   // https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui
    compile group: 'io.springfox', name: 'springfox-swagger-ui', version: '2.6.1'

}

buildscript {
    ext {
        springBootVersion = '1.5.2.RELEASE'
    }
    repositories {
//        mavenCentral()
//        jcenter()
        maven {
            url 'http://maven.aliyun.com/nexus/content/groups/public/'
        }
    }
    dependencies {
        classpath("org.springframework.boot:spring-boot-gradle-plugin:${springBootVersion}")
    }
}

2.配置Swagger的Docket Bean

@Configuration
class SwaggerConfig {

    /**
     * Docket: Springfox’s, primary api configuration mechanism is initialized for swagger specification 2.0
     *
     * A builder which is intended to be the primary interface into the swagger-springmvc framework.
     * Provides sensible defaults and convenience methods for configuration.
     * @return
     */
    @Bean
    Docket myApi() {

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.easy.springboot.h5perf"))
//                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build()

    }

    def apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot集成Swagger2构建自动化Rest API文档")
                .description("Spring Boot开发从0到1教程")
                .version("1.0")
                .build()
    }
}

这个 Docket类,是Springfox 框架的API配置机制实现的builder类。

我们通过@Configuration标记此类为配置类,会在SpringBoot项目启动的时候加载,
实际上我们已经完成了对Swagger的配置,Swagger会自动扫描我们配置的cn.com.wenyi.controller包下的接口自动生成接口文档。

3.配置WebMvc的addResourceHandlers

package com.easy.springboot.h5perf.config

import org.springframework.context.annotation.Configuration
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry
import org.springframework.web.servlet.config.annotation.WebMvcConfigurerAdapter

/**
 * Created by jack on 2017/4/23.
 * http://docs.spring.io/spring-boot/docs/current/api/org/springframework/boot/autoconfigure/web/WebMvcAutoConfiguration.EnableWebMvcConfiguration.html
 */

@Configuration
class WebMvcConfig extends WebMvcConfigurerAdapter {
    @Override
    void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/")

        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/")
    }


}

4.Swagger的API注解在Controller上面的使用

package com.easy.springboot.h5perf.controller

import com.easy.springboot.h5perf.mapper.TestCaseMapper
import com.easy.springboot.h5perf.model.TestCase
import com.easy.springboot.h5perf.result.Result
import groovy.json.JsonOutput
import io.swagger.annotations.Api
import io.swagger.annotations.ApiImplicitParam
import io.swagger.annotations.ApiOperation
import org.springframework.beans.factory.annotation.Autowired
import org.springframework.stereotype.Controller
import org.springframework.ui.Model
import org.springframework.web.bind.annotation.GetMapping
import org.springframework.web.bind.annotation.PostMapping
import org.springframework.web.bind.annotation.RequestParam
import org.springframework.web.bind.annotation.ResponseBody
import springfox.documentation.swagger2.annotations.EnableSwagger2

/**
 * Created by jack on 2017/4/22.
 * http://springfox.github.io/springfox/docs/current/#springfox-samples
 */
@Api(value = "测试任务管理", tags = ["测试任务管理API"], description = "描述信息")
@Controller
class TestCaseController {
    @Autowired
    TestCaseMapper testCaseMapper

    @PostMapping("/saveTestCase")
    @ResponseBody
    def saveTestCase(TestCase testCase) {
        testCase.gmtCreated = new Date()
        println("testCase===" + testCase)
        int insert = testCaseMapper.insert(testCase)
        println("testCase===" + testCase)
        Result result = new Result()
        if (insert == 1) {
            result.success = true
            result.result = testCase
        } else {
            result.success = false
            result.result = testCase
        }
        def jsonOutput = new JsonOutput()
        println("saveTestCase result===" + jsonOutput.toJson(result))
        result
    }

    @GetMapping("/listTestCase")
    def listTestCase(Model model) {
        model.addAttribute("testCaseList", testCaseMapper.findAll())
        "/test_case/list"
    }

    @ApiOperation(value = "list all TestCase Json", notes = "listTestCaseJson", produces = "application/json")
    @GetMapping("/listTestCaseJson")
    @ResponseBody
    def listTestCaseJson() {
        testCaseMapper.findAll()
    }

    @ApiOperation(value = "findOne TestCase Json", notes = "findOne TestCase", produces = "application/json")
    @ApiImplicitParam(name = "id",
            value = "测试任务ID",
            dataType = "Integer",//This can be the class name or a primitive
            required = true,
            paramType = "query")//Valid values are {@code path}, {@code query}, {@code body}, {@code header} or {@code form}
    @GetMapping("/findOne")
    @ResponseBody
    def findOne(@RequestParam(value = "id", required = true) Integer id) {
        testCaseMapper.findOne(id)
    }


}

@API表示这个类提供一个开放的API,可以通过description简要描述该API的功能。
在一个@API下,可有多个@ApiOperation,表示针对该API的CRUD操作。

在ApiOperation Annotation中可以通过value,notes描述该操作的作用,response描述正常情况下该请求的返回对象类型。 在一个ApiOperation下,可以通过ApiResponses描述该API操作可能出现的异常情况。

ApiParam用于描述该API操作接受的参数类型

我们也可以为项目的Model对象添加Swagger Annotation,这样Swagger Scanner可以获取更多关于Model对象的信息。但是,这样感觉侵入的代码有点多。酌情考虑。

5.启动@EnableSwagger2

在Application.groovy 微服务程序入口类上添加注解@EnableSwagger2:

package com.easy.springboot.h5perf

import org.springframework.boot.CommandLineRunner
import org.springframework.boot.SpringApplication
import org.springframework.boot.autoconfigure.SpringBootApplication
import org.springframework.context.annotation.ComponentScan
import org.springframework.web.servlet.config.annotation.EnableWebMvc
import springfox.documentation.swagger2.annotations.EnableSwagger2

/**
 * Created by jack on 2017/4/22.
 */
@SpringBootApplication
@EnableWebMvc
@EnableSwagger2
@ComponentScan("com.easy.springboot.h5perf")
//@MapperScan('com.easy.springboot.h5perf.mapper') // 此处注解,与在Mapper接口上添加@Mapper注解功能等效
class Application implements CommandLineRunner {
    static void main(String[] args) {
        SpringApplication.run(Application.class, args)
    }

    @Override
    void run(String... args) throws Exception {


    }
}

@EnableSwagger2这个注解用来启动Swagger的文档配置功能,我们通过源码可以看到,它Import了配置类Swagger2DocumentationConfiguration。

而Swagger2DocumentationConfiguration类又@Import了SpringfoxWebMvcConfiguration,SwaggerCommonConfiguration配置类。到最后,SpringfoxWebMvcConfiguration类Import了配置类ModelsConfiguration。

Swagger具体的实现原理,可以参考[1]~[6]。

6.运行测试

文档展示

实时测试

小结

Swagger可以充当前后端协同工作,自由联调的重要桥梁。方便快捷。很实用。

使用Swagger,我们可以自由生产,显示和消费自己的RESTful服务。不需要代理和第三方服务。同时,集成swagger-ui,通过Swagger API动态的生成漂亮的文档和API测试空间。

参考资料:
1.http://springfox.github.io/springfox/docs/current/#springfox-configuration-and-demo-applications
2.http://swagger.io/
3.https://github.com/martypitt/swagger-springmvc
4.https://github.com/swagger-api/swagger-ui
5.https://github.com/swagger-api/swagger-core
6.https://github.com/swagger-api/swagger-spec

版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

相关文章
01_spring_ 简介| 学习笔记
快速学习01_spring_ 简介
8 0
02_spring_ioc| 学习笔记
快速学习02_spring_ioc
3 0
冬季实战营第一期:从零到一上手玩转云服务器学习总结
冬季实战营第一期:从零到一上手玩转云服务器学习总结
5 0
Django框架介绍与安装
软件框架就是为实现或完成某种软件开发时,提供了一些基础的软件产品, 框架的功能类似于基础设施,提供并实现最为基础的软件架构和体系 通常情况下我们依据框架来实现更为复杂的业务程序开发 二个字,框架就是程序的骨架
4 0
03_spring_ioc 实现| 学习笔记
快速学习03_spring_ioc 实现
3 0
冬季实战营第一期 学习报告
冬季实战营第一期的训练营日程一共安排了五天。四天的动手实战和一天的直播带练。此文是关于第一期的学习报告。
11 0
python垃圾回收
吃太多,总会变胖,Python也是这样。当Python中的对象越来越多,它们将占据越来越大的内存。不过你不用太担心Python的体形,它会乖巧的在适当的时候“减肥”,启动垃圾回收(garbage collection),将没用的对象清除。在许多语言中都有垃圾回收机制,比如Java。尽管最终目的都是塑造苗条的提醒,但不同语言的减肥方案有很大的差异 。
4 0
Windows下JDK安装与配置(超详细,图文详解、适合小白查看)
Windows下JDK安装与配置(超详细,图文详解、适合小白查看)
8 0
04_spring_ioc 创建对象的方式| 学习笔记
快速学习 04_spring_ioc 创建对象的方式
3 0
初始ECS
物联网学习的硬性需求,我们需要搭建一台自己的服务器,在不断查找资料和方法后,获知阿里云ECS云服务器有学生体验资格,继而我将利用ECS云服务器搭建一个自己的EMQX服务器端。
16 0
+关注
程序员诗人
一个会写诗的程序员
831
文章
14
问答
文章排行榜
最热
最新
相关电子书
更多
《2021云上架构与运维峰会演讲合集》
立即下载
《零基础CSS入门教程》
立即下载
《零基础HTML入门教程》
立即下载