Spring boot下的Swagger2使用指南

最新推荐文章于 2022-11-22 17:35:24 发布

笙箫123

最新推荐文章于 2022-11-22 17:35:24 发布

阅读量672

点赞数 4

分类专栏： spring boot 文章标签： spring boot swagger2

本文链接：https://blog.csdn.net/q15102780705/article/details/100901302

版权

spring boot 专栏收录该内容

19 篇文章 0 订阅

订阅专栏

1、引言

随着微服务架构体系的发展和应用，为了前后端能够更好的集成与对接，同时为了项目的方便交付，每个项目都需要提供相应的API文档。

传统的API文档编写存在以下几个痛点：
1.对API文档进行更新的时候，需要通知前端开发人员，导致文档更新交流不及时；

2.API接口返回信息不明确

3.大公司中肯定会有专门文档服务器对接口文档进行更新。

4.缺乏在线接口测试，通常需要使用相应的API测试工具，比如postman、SoapUI等

5.接口文档太多，不便于管理

为了解决传统API接口文档维护的问题，为了方便进行测试后台Restful接口并实现动态的更新，因而引入Swagger接口工具。

Swagger具有以下优点
1.功能丰富：支持多种注解，自动生成接口文档界面，支持在界面测试API接口功能；

2.及时更新：开发过程中花一点写注释的时间，就可以及时的更新API文档，省心省力；

3.整合简单：通过添加pom依赖和简单配置，内嵌于应用中就可同时发布API接口文档界面，不需要部署独立服务。

2、认识Swagger

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

作用：

1. 接口的文档在线自动生成。

2. 功能测试。

Swagger是一组开源项目，其中主要要项目如下：

1. Swagger-tools:提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger 1.2文档转换成Swagger 2.0文档等功能。

2. Swagger-core: 用于Java/Scala的的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF...)、Servlets和Play框架进行集成。

3. Swagger-js: 用于JavaScript的Swagger实现。

4. Swagger-node-express: Swagger模块，用于node.js的Express web应用框架。

5. Swagger-ui：一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。

6. Swagger-codegen：一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码。

3、Maven

版本号请根据实际情况自行更改。

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
    <version>2.2.2</version>
</dependency>

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.2.2</version>
</dependency>

4、创建Swagger2配置类

在Application.java同级创建Swagger2的配置类Swagger2

package com.example.demo.swagger;
 
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;
 
/**
 * Swagger2配置类
 * 在与spring boot集成时，放在与Application.java同级及以下的目录下。
 * 通过@Configuration注解，让Spring来加载该类配置。
 * 再通过@EnableSwagger2注解来启用Swagger2。
 */
@Configuration
@EnableSwagger2
public class Swagger2 {
    
    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     * 
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo.swagger"))
                .paths(PathSelectors.any())
                .build();
    }
    
    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2构建RESTful APIs")
                .description("更多请关注http://www.baidu.com")
                .termsOfServiceUrl("http://www.baidu.com")
                .contact("sunf")
                .version("1.0")
                .build();
    }
}

如上代码所示，通过createRestApi函数创建Docket的Bean之后，apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）。

5、添加文档内容

在完成了上述配置后，其实已经可以生产文档内容，但是这样的文档主要针对请求本身，描述的主要来源是函数的命名，对用户并不友好，我们通常需要自己增加一些说明来丰富文档内容。

Swagger使用的注解及其说明：

@Api：用在类上，说明该类的作用。

@ApiOperation：注解来给API增加方法说明。

@ApiImplicitParams : 用在方法上包含一组参数说明。

@ApiImplicitParam：用来注解来给方法入参增加说明。

@ApiResponses：用于表示一组响应

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

l code：数字，例如400

l message：信息，例如"请求参数没填好"

l response：抛出异常的类

@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）

l @ApiModelProperty：描述一个model的属性

注意：@ApiImplicitParam的参数说明：

paramType：指定参数放在哪个地方	header：请求参数放置于Request Header，使用@RequestHeader获取 query：请求参数放置于请求地址，使用@RequestParam获取 path：（用于restful接口）-->请求参数的获取：@PathVariable body：（不常用） form（不常用）
name：参数名
dataType：参数类型
required：参数是否必须传	true \| false
value：说明参数的意思
defaultValue：参数的默认值

例子：

package com.example.demo.swagger;

import org.springframework.stereotype.Controller;
import org.springframework.util.StringUtils;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.ResponseBody;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;

/**
 * 
 * <p>
 * Description:
 * </p>
 * 一个用来测试swagger注解的控制器
 * 
 * @author xuyangwei
 * 
 * @date 2019年9月16日
 * 
 */
@Controller
@RequestMapping("/test")
@Api(value = "TestController|一个用来测试swagger注解的控制器")
public class SayController {

	@ResponseBody
	@RequestMapping(value = "/getUserName", method = RequestMethod.GET)
	@ApiOperation(value = "根据用户编号获取用户姓名", notes = "test: 仅1和2有正确返回")
	@ApiImplicitParam(paramType = "query", name = "userNumber", value = "用户编号", required = true, dataType = "Integer")
	public String getUserName(@RequestParam Integer userNumber) {
		if (userNumber == 1) {
			return "张三丰";
		} else if (userNumber == 2) {
			return "慕容复";
		} else {
			return "未知";
		}
	}

	@ResponseBody
	@RequestMapping(value = "/updatePassword")
	@ApiOperation(value = "修改用户密码", notes = "根据用户id修改密码")
	@ApiImplicitParams({
			@ApiImplicitParam(paramType = "query", name = "userId", value = "用户ID", required = true, dataType = "Integer"),
			@ApiImplicitParam(paramType = "query", name = "password", value = "旧密码", required = true, dataType = "String"),
			@ApiImplicitParam(paramType = "query", name = "newPassword", value = "新密码", required = true, dataType = "String") })
	public String updatePassword(@RequestParam(value = "userId") Integer userId,
			@RequestParam(value = "password") String password,
			@RequestParam(value = "newPassword") String newPassword) {
		if (userId <= 0 || userId > 2) {
			return "未知的用户";
		}
		if (StringUtils.isEmpty(password) || StringUtils.isEmpty(newPassword)) {
			return "密码不能为空";
		}
		if (password.equals(newPassword)) {
			return "新旧密码不能相同";
		}
		return "密码修改成功!";
	}
}

6、访问方式

启动Spring Boot程序，访问：http://localhost:8080/swagger-ui.html

如上图，可以看到暴漏出来的控制器信息，点击进入可以看到详细信息。

需要注意的地方：

Conntroller中定义的方法必须在@RequestMapper中显示的指定RequestMethod类型，一般是POST或者GET，否则SawggerUi会默认为全类型皆可访问， API列表中会生成多条项目。

如上图：updatePassword()未指定requestMethod，结果生成了7条API信息。所以如果没有特殊需求，建议根据实际情况加上requestMethod。

笙箫123

关注

4
点赞
踩
3

收藏

觉得还不错? 一键收藏
0
评论
Spring boot下的Swagger2使用指南

1、引言随着微服务架构体系的发展和应用，为了前后端能够更好的集成与对接，同时为了项目的方便交付，每个项目都需要提供相应的API文档。传统的API文档编写存在以下几个痛点：1.对API文档进行更新的时候，需要通知前端开发人员，导致文档更新交流不及时；2.API接口返回信息不明确3.大公司中肯定会有专门文档服务器对接口文档进行更新。4.缺乏在线接口测试，通常需要使用相应的API...
复制链接

扫一扫