目录

?Swagger

?Swagger工具集

Swagger注解

项目总结

新建SpringBoot项目

pom.xml

Swagger2Config配置类

User实体类

UserController控制器

项目测试

添加用户

修改用户

查询用户

删除用户

Swagger

• Swagger是一款基于RESTful接口的用于文档在线自动生成和功能测试的开发工具
• 为了减少前后端开发人员在开发期间的频繁沟通，可以使用Swagger提供的接口文档和线上接口进行前后端功能联调（前端代码和后端代码可以独立开发，后端开发人员不必立即理解前端代码的实现细节**）**
• Swagger工具的功能：
  • 辅助接口设计
  • 辅助接口开发
  • 生成接口文档
  • 进行接口测试
  • Mock接口
  • 接口管理
  • 接口检测
• Swagger可以整合到SpringBoot项目中并生成RESTful API文档，减少了开发者创建文档的工作量，同时将接口的说明内容整合在Java代码中，让维护文档和修改代码合为一体，可以让开发者在修改代码逻辑的同时方便地修改文档说明

Swagger工具集

• Swagger-tools：提供各种与Swagger进行集成和交互的工具。例如模式检验、Swagger1.2文档转换成Swagger2.0文档等功能。
• Swagger-core：用于Java/Scala的Swagger实现。与JAX-RS(Jersey、Resteasy、CXF…）、Servlets和Play框架进行集成。
• Swagger-js：用于JavaScript的Swagger实现。
• Swagger-node-express：Swagger模块，用于node.js的Express web应用框架。
• Swagger-ui：一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。
• Swagger-codegen：一个模板驱动引擎，通过分析用户Swagger资源声明以各种语言生成客户端代码

Swagger注解

• @Configuration：表明这是一个配置类
• @EnableSwagger2：开启Swagger2
• @Api：放在类上，描述一个类的基本信息。
• @ApiOperation：放在方法上，描述一个方法的基本信息
  • value：对方法作用的一个简短描述
  • notes：用来备注该方法的详细作用
• @ApiImplicitParams：用在方法上，包含一组参数说明
• @ApiImplicitParam：用来注解来给方法入参增加说明，一个请求能数
  • paramType：指方法参数的类型，可选值如下
    • path，参数获取方式：@PathVariable
    • query，参数获取方式：@RequestParam
    • header，参数获取方式：@RequestHeader
    • body
    • form
  • name：参数名称，和参数变量相对应
  • value：参数的描述信息
  • required：该字段是否必填
  • defaultValue：该字段的默认值
• @ApiResponses：用于表示一组响应。
• @ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
  • code：响应码
  • message：描述信息，例如“请求参数没填好”
  • response：抛出异常的类
• @ApiModel：用对象来接收参数，描述一个Model的信息（一般用于在请求参数无法使用@ApiImplicitParam注解进行描述的时候）
• @ApiModelProperty：用对象接收参数时，描述对象的一个字段
• @ApiIgnore：不对某个接口生成文档
• @ApiError ：发生错误返回的信息

项目总结

SpringBoot整合Swagger：

1. 引入pom的相关依赖
2. 在代码中加入相应的配置，新建config包，写入swaggerConfig配置类
3. 在basePackage指定的路径下使用swagger（使用api注解，编写控制器类）
4. 启动项目，浏览器打开http://ip:port/swagger-ui.html进行测试

新建SpringBoot项目

项目结构：

pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>2.3.12.RELEASE</version>
		<relativePath/> <!-- lookup parent from repository -->
	</parent>
	<groupId>com.study</groupId>
	<artifactId>springboot_swagger</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<name>springboot_swagger</name>
	<description>Demo project for Spring Boot</description>
	<properties>
		<java.version>8</java.version>
	</properties>
	<dependencies>

		<!--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>

		<dependency>
			<groupId>org.projectlombok</groupId>
			<artifactId>lombok</artifactId>
		</dependency>

		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>

		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
		</dependency>
	</dependencies>

	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>
		</plugins>
	</build>

</project>

Swagger2Config配置类

package com.study.springboot_swagger.config;

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 //启用Swagger API文档
public class Swagger2Config {

    /**
     * 返回实例Docket(Swagger API摘要)
     * 在方法中指定扫描的控制器包路径,
     * 只有在此路径下的Controller类才会自动生成Swagger API文档
     * @return
     */
    @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2)  // 指定 Swagger 的版本为 2
                .apiInfo(apiInfo())  // 设定 API 文档的基本信息
                .select()  // 进入 API 选择模式
                .apis(RequestHandlerSelectors.basePackage("com.study.springboot_swagger.controller"))  // 指定扫描的包路径，Swagger 将扫描该包下的所有 Controller 类
                .paths(PathSelectors.any())  // 指定要包含的路径，PathSelectors.any() 表示包括所有路径
                .build();  // 完成 Docket 实例的构建
    }

    /**
     * 配置一些基本的显示信息,
     * 比如标题,描述,版本,服务条款,联系方式等
     * @return
     */
    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("swagger-api文档")
                .description("swagger 文档 by liufu")
                .version("1.0")
                .build();
    }
}

User实体类

package com.study.springboot_swagger.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

@ApiModel(value = "用户实体类", description = "用户信息描述类")
@Data //getter,setter方法
public class User{
    @ApiModelProperty(value = "用户名")
    private String username;

    @ApiModelProperty(value = "用户地址")
    private String address;
}

UserController控制器

package com.study.springboot_swagger.controller;

import com.study.springboot_swagger.entity.User;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;

@RestController
@Api(tags = "用户数据接口")
public class UserController {

    @ApiOperation(value = "查询用户", notes = "根据id查询用户")
    @ApiImplicitParam(paramType = "path", name = "id", value = "用户id", required = true)
    @GetMapping("/user/{id}")
    public String getUserById(@PathVariable Integer id){
        return "/user/"+id;
    }

    @ApiResponses({
            @ApiResponse(code = 200, message = "删除成功!"),
            @ApiResponse(code = 500, message = "删除失败!")
    })
    @ApiOperation(value = "删除用户", notes = "通过id删除用户")
    @DeleteMapping("/user/{id}")
    public Integer deleteUserById(@PathVariable Integer id){
        return id;
    }

    @ApiOperation(value = "添加用户", notes = "添加一个用户,传入用户名和地址")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType = "query", name = "username", value = "用户名", required = true, defaultValue = "sang"),
            @ApiImplicitParam(paramType = "query", name = "address", value = "用户地址", required = true, defaultValue = "shenzhen")
    })
    @PostMapping("/user")
    public String addUser(@RequestParam String username, @RequestParam String address){
        return username + ":" + address;
    }

    @ApiOperation(value = "修改用户", notes = "修改用户,传入用户信息")
    @PutMapping("/user")
    public String updateUser(@RequestBody User user){
        return user.toString();
    }

    @GetMapping("/ignore")
    @ApiIgnore
    public void ignoreMethod(){

    }
}

项目测试

访问网址：http://localhost:8080/swagger-ui.html，查看接口文档

展开一个接口描述，单击Try it out ，在Parameters区域填写信息，点击 Execute 进行接口测试，Responses区域为测试结果

添加用户

修改用户

查询用户

删除用户