使用语言：JAVA

使用框架：SpringBoot

构建工具：maven

使用插件：lombok

首先，需要使用maven在我们的springboot项目中导入swagger的starter包：

在pom.xml加入如下配置：

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

然后，我们需要创建一个配置类：

import io.swagger.annotations.Api;
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.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class Swagger3Config {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30)
                .enable(true)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("文档测试")
                .description("这是一个文档测试")
                .contact(new Contact("cuijian", "#", "cuijian.1997@qq.com"))
                .version("v1.0")
                .build();
    }

}

然后，我们需要创建一个Controller，用来展示接口数据：

import com.xx.api.annotation.LoginRequired;
import com.xx.api.common.JsonResult;
import com.xx.api.service.ImageService;
import com.xx.api.vo.common.FileVo;
import io.swagger.annotations.*;
import io.swagger.v3.oas.annotations.parameters.RequestBody;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.*;

import javax.servlet.http.HttpServletRequest;
import java.io.IOException;
import java.util.List;

@Api(value = "图片头像相关接口", tags = {"图片头像相关接口"})
@RestController
@RequestMapping("/image")
@Validated
public class ImageController {

    /**
     * 上传头像
     * @param fileVo 头像文件
     * @return 图像地址
     */
    @ApiOperation("上传头像，限制大小：10M以内，图片会被压缩为300* 300")
    @ApiResponses({
            @ApiResponse(code = 200, message = "上传成功，返回图片地址", response = JsonResult.class),
            @ApiResponse(code = 410, message = "你需要登录来访问资源", response = JsonResult.class),
            @ApiResponse(code = 480, message = "上传文件错误，请检查后上传", response = JsonResult.class)
    })
    @LoginRequired
    @PostMapping(value = "/uploadProfile.muse")
    public JsonResult<String> uploadProfile(@RequestBody FileVo fileVo) {
        return JsonResult.success();
    }
}

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;
import org.springframework.web.multipart.MultipartFile;

@Data
public class FileVo {

    @Schema(description = "Multipart格式的图片", required = true)
    private MultipartFile file;

}

import lombok.Data;
import lombok.ToString;

import java.io.Serializable;

@Data
@ToString
public class JsonResult<T> implements Serializable {

    private int status = 200;

    private String msg;

    private T data;

    private JsonResult(){}

    private JsonResult(String msg){
        this.msg = msg;
    }
    private JsonResult(T data) {
        this.data = data;
    }
    private JsonResult(int status, String msg) {
        this.status = status;
        this.msg = msg;
    }
    private JsonResult(String msg, T data) {
        this.msg = msg;
        this.data = data;
    }
    private JsonResult(int status, String msg, T data) {
        this.status = status;
        this.msg = msg;
        this.data = data;
    }
    public static <T> JsonResult<T> success(){
        return new JsonResult<>("success!");
    }
    public static <T> JsonResult<T> success(T data) {
        return new JsonResult<>("success!", data);
    }
    public static <T> JsonResult<T> success(String msg, T data) {
        return new JsonResult<>(msg, data);
    }
    public static <T> JsonResult<T> error(ResultCode resultCode) {
        return new JsonResult<>(resultCode.getCode(), resultCode.getMessage());
    }
    public static <T> JsonResult<T> error(ResultCode resultCode, Exception e) {
        return new JsonResult<>(resultCode.getCode(), resultCode.getMessage() + e.getMessage());
    }
    public static <T> JsonResult<T> error(ResultCode resultCode, T data) {
        return new JsonResult<>(resultCode.getCode(), resultCode.getMessage(), data);
    }
}

然后，运行项目，打开地址：http://${你的地址}:${你的端口}/swagger-ui/index.html

文档就生效了，接下来，我还会补充一些文档的细节部分，因为目前大多数使用的还是swagger2，导致swagger3的指导并不多，我也是被一些其他的博客文章误导，走了很多弯路，我会把我曾经遇到的问题都记录下来，争取让后面的人不会在编写文档上浪费大量的时间。