一、前言
Spring Boot作为当前最为流行的Java web开发脚手架,越来越多的开发者选择用其来构建企业级的RESTFul API接口。这些接口不但会服务于传统的web端(b/s),也会服务于移动端。在实际开发过程中,这些接口还要提供给开发测试进行相关的白盒测试,那么势必存在如何在多人协作*享和及时更新API开发接口文档的问题。
使用 Swagger 集成文档具有以下几个优势:
- 功能丰富 :支持多种注解,自动生成接口文档界面,支持在界面测试API接口功能;
- 及时更新 :开发过程中花一点写注释的时间,就可以及时的更新API文档,省心省力;
- 整合简单 :通过添加pom依赖和简单配置,内嵌于应用中就可同时发布API接口文档界面,不需要部署独立服务。
接下来,我们通过Spring Boot来整合Swagger实现在线API文档的功能,本文用的是SpringFox Swagger2,版本2.9.2(最新版本是3.0.0,但是在我测试是swagger-ui.html页面一直出不来,在https://mvnrepository.com/上也可以看到,2.9.2是目前使用最多的版本)
二、创建Spring Boot工程
我用的开发工具是IDEA,通过IDEA快速创建一个Spring Boot工程,创建时,只需勾选web依赖选项就成,不勾选也没关系,后面在pom.xml中配置也是一样的。注意创建工程时,工程名称都要是小写。
添加Swagger的两个依赖
<!-- swagger -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
三、添加配置类
添加一个swagger 配置类,在工程下新建 config 包并添加一个 SwaggerConfig 配置类SwaggerConfig.java。
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
@Configuration
@EnableSwagger2
public class SwaggerConfig {
@Bean
public Docket createRestApi(){
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo(){
return new ApiInfoBuilder()
.title("在线API文档")
.description("This is a restful api document of demo")
.version("1.0")
.build();
}
}
以上就已经完成了Swagger的配置,是不是很简洁轻松。
四、创建一个测试Controller来验证配置
添加一个控制器,在工程下新建 controller包并添加一个 HelloController控制器HelloController.java。
package com.louis.springboot.demo.controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
/* 类注解 */
@Api
@RestController
public class HelloController {
/* 方法注解 */
@ApiOperation(value = "desc of method", notes = "")
@GetMapping(value="/hello")
public Object hello( @ApiParam(value = "desc of param" , required=true ) @RequestParam String name) {
return "Hello " + name + "!";
}
}
五、编译运行测试
启动工程, 打开浏览器,访问:http://localhost:8080/swagger-ui.html,进入swagger接口文档界面。
完毕收工,这样管理API接口很方便,并且是和代码实时更新的,不用烦心再去写接口文档啦。
附录:Swagger常用注解
API | 使用位置 |
---|---|
@Api | 用于controller类上,表示标识这个类是swagger的资源 |
@ApiOperation | 用在controller的方法上,表示一个http请求的操作 |
@ApiParam | 方法中的参数注释 |
@ApiResponses | 用在controller的方法上 |
@ApiResponse | 用在 @ApiResponses里边 |
@ApiImplicitParams | 用在controller的方法上 |
@ApiImplicitParam | 用在@ApiImplicitParams的方法里边 |
@ApiModel | 用在返回对象类上 |
WEB项目开发中碰到的问题千奇百怪,大家想了解对如何快速的掌握Spring Boot,可以参见视频:
51CTO:Spring Boot+Bootstrap开发小而完整web项目
腾讯课堂:Spring Boot+Bootstrap开发小而完整web项目
CSDN学院:Spring Boot+Bootstrap开发小而完整web项目
网易云课堂:Spring Boot+Bootstrap开发小而完整web项目