Springboot整合Swagger、Swagger详解及Swagger常用注解

Swagger是什么？它能干什么？

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测

Swagger的优势

1.支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
2.提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

快速搭建springboot项目

1.访问：https://start.spring.io/
2. 根据页面提示，选择构建工具，开发语言，项目信息等。
3.
4.点击 Generate the project，生成项目模板，生成之后会将压缩包下载到本地
5.解压使用IDE导入项目

添加Swagger Maven依赖

    
        io.springfox
        springfox-swagger2
        2.9.2
    
    
        io.springfox
        springfox-swagger-ui
        2.9.2
    

编写Swagger配置类

package com.project.becurrent.common.config.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;

/**
 * @Description:SwaggerConfig
 * @Author: wk
 * @CreateDate: 2020/10/15 13:50
 * @Version: 1.0
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {
     

	/**
     *  通过createRestApi函数创建Docket的Bean之后，
     *  * apiInfo()用来创建该Api的基本信息（这些基本信息会展现在文档页面中）
     *  * select()函数返回一个ApiSelectorBuilder实例用来控制哪些接口暴露给Swagger来展现，
     *  * apis()函数扫描所有Controller中定义的API， 并产生文档内容（除了被@ApiIgnore指定的请求）
     * @return
     * @date        2020/10/15 16:24
     */
    @Bean
    public Docket createRestApi() {
     
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(aipInfo()).select()
                .apis(RequestHandlerSelectors.basePackage("com.project.becurrent"))//包名换成自己的
                .paths(PathSelectors.any()).build();
    }
	 /**
     * 创建该Api的基本信息（这些基本信息会展现在文档页面中）
     * @return
     */
    private ApiInfo aipInfo() {
     
        return new ApiInfoBuilder()
                //页面标题
                .title("be-current Swagger API接口").description("be-current Swagger API接口文档")
                .build();
    }
}

集成 Swagger 管理 API 文档

controller中的使用

package com.project.becurrent.system.controller;

import com.alibaba.fastjson.JSON;
import com.project.becurrent.common.util.Result;
import com.project.becurrent.common.util.encrypt.MD5Util;
import com.project.becurrent.system.domain.UserDO;
import com.project.becurrent.system.service.UserService;
import io.swagger.annotations.*;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.autoconfigure.thymeleaf.ThymeleafProperties;
import org.springframework.stereotype.Controller;
import org.springframework.ui.Model;
import org.springframework.web.bind.annotation.*;

/**
 * @Author: wk
 * @CreateDate: 2020/10/12 9:33
 * @Version: 1.0
 */
@Controller
@Api(value = "LoginController", tags = {
     "登录接口"})
public class LoginController {
     

    @Autowired
    private UserService userService;

    @GetMapping("/login")
    @ApiOperation("登录页面跳转")
    public String login() {
     
        return "login";
    }

    @PostMapping("/submit")
    @ResponseBody
    @ApiOperation("登录接口")
    @ApiImplicitParams({
     
            @ApiImplicitParam(name = "username", value = "username", dataType = "String", required = true),
            @ApiImplicitParam(name = "password", value = "password", dataType = "String", required = true),
            @ApiImplicitParam(name = "verifyCode", value = "verifyCode", dataType = "String", required = true),
    })
    public Result login(@RequestParam("username") String username, @RequestParam("password") String password, @RequestParam("verifyCode") String verifyCode) {
     
        UserDO userDO = userService.getByUsername(username);
        if (userDO == null) return Result.error("账号错误，请重新输入！");
        if (!MD5Util.encrypt(username, password).equals(userDO.getPassword())) {
     
            return Result.error("账号或密码错误，请重试！");
        }
        return Result.success();
    }

    @ApiOperation("test")
    @PostMapping("/test")
    public Result test(@ApiParam(value = "参数说明",name = "参数名",required = true) String test){
     
        return null;
    }

}

domain中的使用

package com.project.becurrent.system.domain;

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

import java.io.Serializable;

@Data
@ApiModel(value = "",description = "描述")
public class UserDO implements Serializable {
     
    private static final long serialVersionUID = 1L;
    //
    @ApiModelProperty(value = "用户id",name = "userId",required = true,example = "举例")
    private Long userId;
    // 用户名
    @ApiModelProperty(value = "用户名d",name = "username",required = true,example = "举例")
    private String username;
   
}

编写好后启动项目并访问 ip+:”端口号/swagger-ui.html 例如：127.0.0.1:8888/swagger-ui.html

当看到此页面说明Swagger整合成功

Swagger常用注解说明

1：@Api()用于类，表示标识这个类是swagger的资源 ，一般用于Controller类上；
2：@ApiOperation()用于方法，表示一个http请求的操作，对接口方法进行一个说明；
3：@ApiParam()用于方法参数说明，表示对参数的添加元数据（说明或是否必填等）；
4：@ApiModel()用于类，表示对类进行说明，一般用于参数用实体类接收 ；
5：@ApiModelProperty()用于实体类字段上，表示对字段进行说明，可以配合@ApiModel()使用；
6：@ApiIgnore()用于类、方法、方法参数上，表示这个类、方法、方法参数被忽略；不生成该类、该方法、该方法参数的文档；
7：@ApiImplicitParam() 用于方法 ，表示单独的请求参数 ；
8：@ApiImplicitParams() 用于方法，包含多个 @ApiImplicitParam()；
9：@ApiResponses()注解在方法上表响应，一般与@ApiResponse公用

@Api()

@Api()用于类；表示标识这个类是swagger的资源
tags——表示说明
value——也是说明，可以使用tags替代 ，但是tags如果有多个值，会生成多个list
例：@Api(value = “LoginController”, tags = {“登录接口”})
效果图如下：

@ApiOperation()

用于方法；表示一个http请求的操作
value——用于方法的描述
notes——用于提示内容
tags——用于重新分组视情况而用）
例： @ApiOperation(“test”)
效果图如下：

@ApiParam()

用于方法，参数，字段说明；表示对参数的添加元数据（说明或是否必填等）
name——参数名
value——参数说明
required——是否必填
例：@ApiParam(value = “test”,name = “test”,required = true)
效果图如下：

@ApiModel()

用于类 ；表示对类进行说明，用于参数用实体类接收
value——表示对象名 （可省略）
description——描述 （可省略）

@ApiModelProperty()

value——字段说明
name——重写属性名字
dataType——重写属性类型
required——是否必填
example——举例说明
hidden——隐藏

@ApiIgnore()

用于类或者方法上，可以不被swagger显示在页面上

@ApiImplicitParam()

用于方法 表示单独的请求参数
name——参数明
value——参数说明
dataType——数据类型
paramType——参数类型
example——举例说明
例：@ApiImplicitParam(name=“name”,value=“用户名”,dataType=“String”, paramType = “query”)

@ApiImplicitParams()

用于方法，包含多个 @ApiImplicitParam
例：
@ApiImplicitParams({ @ApiImplicitParam(name="name",value="用户名",dataType="String", paramType = "query"),@ApiImplicitParam(name="name",value="用户名",dataType="String", paramType = "query"),@ApiImplicitParam(name="name",value="用户名",dataType="String", paramType = "query") })