在SpringBoot项目中的使用Swagger的方法示例

一. 首先Swagger是什么?

在这里插入图片描述

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

作用：
1. 接口的文档在线自动生成。
2. 功能测试。

Swagger的主见介绍:

在这里插入图片描述

Swagger Codegen: 通过Codegen 可以将描述文件生成html格式和cwiki形式的接口文档，同时也能生成多钟语言的服务端和客户端的代码。支持通过jar包，docker，node等方式在本地化执行生成。也可以在后面的Swagger Editor中在线生成。

Swagger UI: 提供了一个可视化的UI页面展示描述文件。接口的调用方、测试、项目经理等都可以在该页面中对相关接口进行查阅和做一些简单的接口请求。该项目支持在线导入描述文件和本地部署UI项目。

Swagger Editor: 类似于markendown编辑器的编辑Swagger描述文件的编辑器，该编辑支持实时预览描述文件的更新效果。也提供了在线编辑器和本地部署编辑器两种方式。

Swagger Inspector: 感觉和postman差不多，是一个可以对接口进行测试的在线版的postman。比在Swagger UI里面做接口请求，会返回更多的信息，也会保存你请求的实际请求参数等数据。

Swagger Hub: 集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到Swagger Hub中。在Swagger Hub中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

PS：
Springfox Swagger: Spring 基于 swagger 规范，可以将基于 SpringMVC 和 Spring Boot 项目的项目代码，自动生成 JSON 格式的描述文件。本身不是属于 Swagger 官网提供的，在这里列出来做个说明，方便后面作一个使用的展开。

二. Swagger UI的使用:

Swagger注解解释:

@Api：请求类的说明
@Api：放在请求的类上，与 @Controller 并列，说明类的作用，如用户模块，订单类等。
tags="说明该类的作用"
value="该参数没什么意义，所以不需要配置"

常用注解：
- @Api()用于类；
表示标识这个类是swagger的资源
- @ApiOperation()用于方法；
表示一个http请求的操作
- @ApiParam()用于方法，参数，字段说明；
表示对参数的添加元数据（说明或是否必填等）
- @ApiModel()用于类
表示对类进行说明，用于参数用实体类接收
- @ApiModelProperty()用于方法，字段
表示对model属性的说明或者数据操作更改
- @ApiIgnore()用于类，方法，方法参数
表示这个方法或者类被忽略
- @ApiImplicitParam() 用于方法
表示单独的请求参数
- @ApiImplicitParams() 用于方法
包含多个 @ApiImplicitParam

(1). @Api: 请求类的说明

@Api：放在 请求的类上，与 @Controller 并列，说明类的作用，如用户模块，订单类等。
tags="说明该类的作用"
value="描述该类作用" [推荐用这个]

@Api 其它属性配置：

属性名称 备注
value url的路径值
tags 如果设置这个值、value的值会被覆盖
description 对api资源的描述
basePath 基本路径
position 如果配置多个Api 想改变显示的顺序位置
produces 如, “application/json, application/xml”
consumes 如, “application/json, application/xml”
protocols 协议类型，如: http, https, ws, wss.
authorizations 高级特性认证时配置
hidden 配置为true ，将在文档中隐藏

(2). @ApiOperation：方法的说明

@ApiOperation："用在请求的方法上，说明方法的作用"
	  value="说明方法的作用"
	  notes="方法的备注说明"

(3). @ApiImplicitParams、@ApiImplicitParam：方法参数的说明

@ApiImplicitParams：用在请求的方法上，包含一组参数说明
@ApiImplicitParam：对单个参数的说明
name：参数名
value：参数的汉字说明、解释
required：参数是否必须传
paramType：参数放在哪个地方
· header --> 请求参数的获取：@RequestHeader
· query --> 请求参数的获取：@RequestParam
· path（用于restful接口）--> 请求参数的获取：@PathVariable
· body（请求体）--> @RequestBody User user
· form（普通表单提交）
dataType：参数类型，默认String，其它值dataType="Integer"
defaultValue：参数的默认值

示例:

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

	@ApiOperation(value="用户登录",notes="随边说点啥")
	@ApiImplicitParams({
		@ApiImplicitParam(name="mobile",value="手机号",required=true,paramType="form"),
		@ApiImplicitParam(name="password",value="密码",required=true,paramType="form"),
		@ApiImplicitParam(name="age",value="年龄",required=true,paramType="form",dataType="Integer")
	})
	@PostMapping("/login")
	public JsonResult login(@RequestParam String mobile, @RequestParam String password,
	@RequestParam Integer age){
		//...
	    return JsonResult.ok(map);
	}
}

(4). @ApiResponses、@ApiResponse：方法返回值的说明

@ApiResponses：方法返回对象的说明
	@ApiResponse：每个参数的说明
	    code：数字，例如400
	    message：信息，例如"请求参数没填好"
	    response：抛出异常的类

(5). @ApiModel：用于JavaBean上面，表示一个JavaBean（如：响应数据）的信息

@ApiModel：用于JavaBean的类上面，表示此 JavaBean 整体的信息
			（这种一般用在post创建的时候，使用 @RequestBody 这样的场景，
			请求参数无法使用 @ApiImplicitParam 注解进行描述的时候 ）

(6). @ApiModelProperty：用在JavaBean类的属性上面，说明属性的含义

@ApiModel(description= "返回响应数据")
public class RestMessage implements Serializable{

	@ApiModelProperty(value = "是否成功")
	private boolean success=true;
	@ApiModelProperty(value = "返回对象")
	private Object data;
	@ApiModelProperty(value = "错误编号")
	private Integer errCode;
	@ApiModelProperty(value = "错误信息")
	private String message;
		
	/* getter/setter 略*/
}

三. Swagger整合SpringBoot

1. Pom依赖:

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

2. 配置类:

package com.zhiyou100.configBeans;

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;

/**
 * @Author ZhengZiXuan
 * @Desc
 */
@Configuration // @Configuration注解，让Spring来加载该类配置。
@EnableSwagger2 //@EnableSwagger2注解来启用Swagger2
public class SwaggerConfigBean {
    /**
     * 创建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.zhiyou100.controller"))
                .paths(PathSelectors.any())
                .build();
    }
    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("使用Swagger2 构建RESTful APIS - 废物")
                .description("废物 - Swagger使用演示")
                .termsOfServiceUrl("www.zzxBIuBIuBIu.com")
                .version("1.0")
                .build();
    }

}

3. 正常的Controller再加Swagger注解:

package com.zhiyou100.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.ResponseBody;

/**
 * @Author ZhengZiXuan
 * @Desc
 */
@Controller
@Api("测试Swagger 的Controller类")
public class TestController {
    @ApiOperation(value="根据id查询名字",notes = "备注:无")
    @ApiImplicitParam(name = "id",value = "用户id",required = true,
            paramType = "query",dataType = "Integer")
    @RequestMapping("/getNameById")
    @ResponseBody
    public String getNameById(int id){
        return "张三";
    }
}

4.启动测试:

http://localhost:8080/swagger-ui.html

四. 访问404Bug的解决方法

在这里插入图片描述

Swagger UI 界面介绍:

在这里插入图片描述

五. Model对象增删改查演示

对User类实现增删改查,生成api文档

package com.zhiyou100.model;

/**
 * @Author ZhengZiXuan
 * @Date 2021/05/10
 * @Desc
 */

public class User {

    private int id;
    private String name;
    private String password;

    @Override
    public String toString() {
        return "User{" +
                "id=" + id +
                ", name='" + name + '\'' +
                ", password='" + password + '\'' +
                '}';
    }

    public User() {
    }

    public int getId() {
        return id;
    }

    public void setId(int id) {
        this.id = id;
    }

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }

    public User(int id, String name, String password) {
        this.id = id;
        this.name = name;
        this.password = password;
    }
}

package com.zhiyou100.controller;

import com.zhiyou100.model.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

import java.util.ArrayList;
import java.util.List;

/**
 * @Author ZhengZiXuan
 * @Date 2021/05/10
 * @Desc  
有点BUG  就是list集合中的增删改
 */
@RestController
@Api("User类的增删改查API")
public class UserController {
    ArrayList<User> users = null;
    public UserController(){
        users = new ArrayList<>();
        users.add(new User(1,"张三","123"));
        users.add(new User(2,"李四","1234"));
        users.add(new User(3,"王五","12345"));
        System.out.println("init users "+users);
    }
    /**
     * 根据id查User
     */
    @ApiOperation("根据id查用户")
    @ApiImplicitParam(name = "id",value = "用户id",
                      required = true,paramType = "path",
                        dataType = "Integer")
    @RequestMapping(value="/user/get/{id}",method = RequestMethod.GET)
    public User getUserById(@PathVariable("id") Integer id){
        System.out.println("getUserById id: "+id);
        if (id != null){
            if (id>0 && id <4){
                User user = users.get(id);
                System.out.println("getUserById User: "+user);
                return user;
            }
        }
        return null;
    }
    /**
     * 查全部user
     */
    @ApiOperation("查询全部用户")
    @RequestMapping(value="/user/get",method = RequestMethod.GET)
    public List<User> getAllUser(){
        System.out.println("getAllUser");
        return users;
    }

    /**
     * 添加User
     */
    @ApiOperation("添加用户")
    @ApiImplicitParam(name="user",value = "用户对象",paramType = "body",dataType = "User")
    @RequestMapping(value="/user/add",method = RequestMethod.POST)
    public User addUser(@RequestBody User user){
        System.out.println("addUser User:"+user);
        if (user == null || user.getId() == 0){
            return null;
        }
        users.add(user);
        return user;
    }

    /**
     * 删除User
     */
    @ApiOperation("根据id删除用户")
    @ApiImplicitParam(name = "id",value = "用户id",
            required = true,paramType = "path",
            dataType = "Integer")
    @RequestMapping(value="/user/delete/{id}",method = RequestMethod.DELETE)
    public boolean delUserById(@PathVariable("id") Integer id){
        System.out.println("delUserById id:"+id);
        if (id != null){
            users.remove(id);
            return true;
        }
        return false;
    }

    /**
     * 更新User
     */
    @ApiOperation("根据id更新用户")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id",value = "用户id",
                    required = true,paramType = "path",
                    dataType = "Integer"),
            @ApiImplicitParam(name = "user",value = "用户对象",
                    required = true,paramType = "body",
                    dataType = "User")})
    @RequestMapping(value="/user/update/{id}",method = RequestMethod.PUT)
    public boolean UpdateUserById(@PathVariable("id") Integer id,@RequestBody User user){
        System.out.println("UpdateUserById id:"+id+"  ,   User:"+user);
        if (id != null && user != null){
            users.add(id,user);
            return true;
        }
        return false;
    }

}

在这里插入图片描述