SpringBoot轻松集成Swagger

文章目录

一、简介
二、SpringBoot集成Swagger
- 第一步：创建一个SpringBoot项目
- 第二步：引入maven坐标
- 第三步：写yml
- 第四步：主启动
- 第五步：创建SwaggerConfig配置类
- 第六步：使用swagger注解进行标识和说明
三、注解说明与测试

一、简介

官网：/

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。简单的说，swagger让我们不在手写接口文档，在前后端分离的情况下，更好维护接口文档
作用：
1.在线自动生成接口文档
2.接口测试【再也不需要像之前一样，在Postman中手写访问地址，参数，值，请求方式】

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

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

二、SpringBoot集成Swagger

第一步：创建一个SpringBoot项目

第二步：引入maven坐标

<parent>
        <groupId></groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.1.</version>
        <relativePath/> 
    </parent>
<dependencies>
<!--        swagger包-->
        <dependency>
            <groupId></groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>
        <!-- swagger-ui -->
        <dependency>
            <groupId></groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>
    </dependencies>

第三步：写yml

# 这里暂时只写端口号
server:
  port: 8091

第四步：主启动

@SpringBootApplication
public class SwaggerDemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(SwaggerDemoApplication.class, args);
    }
}

第五步：创建SwaggerConfig配置类


/**
 * SwaggerConfig配置类
 * 在与spring boot集成时，放在与同级的目录下。
 * 通过@Configuration注解，让Spring来加载该类配置。
 * 再通过@EnableSwagger2注解来启用Swagger2。
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com"))
                .paths(PathSelectors.any()).build();
    }


    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot集成swagger")
                .description("@筱筱攻城狮")
                .termsOfServiceUrl("/qq_44799924?spm=1018.2226.3001.5343")
                .version("1.0").build();
    }
}

第六步：使用swagger注解进行标识和说明

@Api(tags = "测试")
@RestController
public class TestController {

    @ApiOperation("测试接口")
    @PostMapping(value = "/hello")
    public String TestController(@RequestParam(value = "name", defaultValue = "张三") String name) {
        return name+":访问成功！";
    }
}

第七步：启动测试
在这里插入图片描述
测试结果：

能看到这个界面说明SpringBoot集成Swagger成功！

三、注解说明与测试

说明;这里只测试常用的属性，其他属性可自行测试

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

@Api 其它属性配置：
在这里插入图片描述

示例：这里只测试

@Api(tags="用户模块")
@Controller
public class UserController {

}

@ApiOperation：用在请求的方法上，说明方法的作用。

value：说明方法的作用
notes：方法的备注

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

@ApiImplicitParam：对单个参数的说明。

@ApiImplicitParams：用在请求的方法上，包含一组参数说明

name：参数名
value：参数的说明、描述
required：参数是否必须必填
paramType：参数放在哪个地方
- query --> 请求参数的获取：@RequestParam
- header --> 请求参数的获取：@RequestHeader
- path（用于restful接口）–> 请求参数的获取：@PathVariable
- body（请求体）–> @RequestBody User user
- form（普通表单提交）
dataType：参数类型，默认String，其它值dataType=“Integer”
defaultValue：参数的默认值

示例：

	@PostMapping("/updatePassword")
    @ApiOperation(value="修改用户密码", notes="根据用户id修改密码")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType="query", name = "userId", value = "用户ID", required = true, dataType = "number"),
            @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 "密码修改成功!";
    }

测试结果：
在这里插入图片描述
不过笔者一般不用这个注解来标识字段，一般用@ApiParam("用户ID")【简单】，

@ApiResponses：用于表示一组响应

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

code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类

示例：

	@ApiOperation("获取用户信息")
    @ApiImplicitParams({
            @ApiImplicitParam(paramType="query", name="userId", dataType="String", required=true, value="用户Id")
    })
    @ApiResponses({
            @ApiResponse(code = 200, message = "请求成功"),
            @ApiResponse(code = 400, message = "请求参数没填好"),
            @ApiResponse(code = 404, message = "请求路径没有或页面跳转路径不对")
    })
    @ResponseBody
    @PostMapping("/list")
    public String list(@RequestParam String userId) {
        return userId+ ":访问成功！";
    }

@ApiModel：用于JavaBean上面，表示对JavaBean 的功能描述

@ApiModel的用途有2个：

当请求数据描述，即 @RequestBody 时，用于封装请求（包括数据的各种校验）数据；
当响应值是对象时，即 @ResponseBody 时，用于返回值对象的描述。

@ApiModelProperty：用在JavaBean类的属性上面，说明属性的含义
在这里插入图片描述

示例：

1.实体类

@Data
@ApiModel("用户实体类")
public class User {
    @ApiModelProperty(value = "用户名",required = true)
    private String username;

    @ApiModelProperty(value = "密码")
    private String password;
}

	@ApiOperation("获取用户信息")
    @PostMapping("/getUser")
    public User getUser(){
        return new User();
    }

测试结果：
在这里插入图片描述

注意事项：
1.若Ctroller使用@RequestMapping而没有指定具体方式，Swagger默认会将所有的请求方式都展示出来，见下图：
在这里插入图片描述
这肯定不是我们想看到的，所以我们一般会指定请求方式，有两种写法，看个人喜欢

@RequestMapping(value ="/getUserName",method = )
@PostMapping(value ="/getUserName")【笔者更喜欢这种，简单直接】

秒客网