Spring?Boot中使用Swagger3.0.0版本構(gòu)建RESTful?APIs的方法

更新時(shí)間：2022年11月15日 10:30:51 作者：劉大貓.

Swagger?是一個(gè)規(guī)范和完整的框架，用于生成、描述、調(diào)用和可視化?RESTful?風(fēng)格的?Web?服務(wù)，這篇文章主要介紹了Spring?Boot中使用Swagger3.0.0版本構(gòu)建RESTful?APIs的方法,需要的朋友可以參考下

一、項(xiàng)目描述

為了練習(xí)Spring Boot中使用Swagger3.0.0版本生成可視化的swagger接口文檔
本項(xiàng)目涉及的版本

Spring版本：5.3.22
SpringBoot版本：2.7.3
Swagger版本：3.0.0

二、簡(jiǎn)介

一般我們?cè)趯?duì)接前后端的時(shí)候，都需要提供相應(yīng)的接口文檔。對(duì)于后端來(lái)說(shuō)，編寫接口文檔即費(fèi)時(shí)費(fèi)力，還會(huì)經(jīng)常因?yàn)闆](méi)有及時(shí)更新，導(dǎo)致前端對(duì)接時(shí)出現(xiàn)實(shí)際接口與文檔不一致。而且手寫接口文檔還容易出錯(cuò)，而swagger很好的解決了這個(gè)痛點(diǎn)。

Swagger 是一個(gè)規(guī)范和完整的框架，用于生成、描述、調(diào)用和可視化 RESTful 風(fēng)格的 Web 服務(wù)?？捎糜冢?.接口的文檔在線自動(dòng)生成、2.功能測(cè)試。

三、Swagger2.X和Swagger3.0.0 的對(duì)比

1）SpringFox 2.x 發(fā)布

此版本的亮點(diǎn)：

號(hào)稱時(shí)最流行的 API 框架
接口文檔在線生成，避免同步的麻煩
可以支持在線對(duì)接口執(zhí)行測(cè)試
支持多語(yǔ)言

SpringBoot項(xiàng)目整合swagger2需要用到兩個(gè)依賴：springfox-swagger2和springfox-swagger-ui，用于自動(dòng)生成swagger文檔。

springfox-swagger2：這個(gè)組件的功能用于幫助我們自動(dòng)生成描述API的json文件
springfox-swagger-ui：就是將描述API的json文件解析出來(lái)，用一種更友好的方式呈現(xiàn)出來(lái)。

2）SpringFox 3.0.0 發(fā)布

此版本的亮點(diǎn)：

Spring5，Webflux支持（僅支持請(qǐng)求映射，尚不支持功能端點(diǎn)）。
Spring Integration支持。
SpringBoot支持springfox Boot starter依賴性（零配置、自動(dòng)配置支持）。
支持OpenApi 3.0.3。
零依賴。幾乎只需要spring-plugin，swagger-core ，現(xiàn)有的swagger2注釋將繼續(xù)工作并豐富openapi3.0規(guī)范。

兼容性說(shuō)明：

需要Java 8
需要Spring5.x（未在早期版本中測(cè)試）
需要SpringBoot 2.2+（未在早期版本中測(cè)試）

3）swagger3.0 與2.xx配置差異：

應(yīng)用主類添加注解@EnableOpenApi (swagger2是@EnableSwagger2)
swagger配置類SwaggerProperties.class，與swagger2.xx 版本有差異，具體看下文
自定義一個(gè)配置類 SwaggerConfiguration.class,看下文
訪問(wèn)地址：http://localhost:8080/swagger-ui/index.html
(swagger2.xx版本訪問(wèn)的地址為http://localhost:8080/swagger-ui.html)

四、注解說(shuō)明

注意：注解中其實(shí)會(huì)有很多的屬性，該文章只列出部分常用的屬性而已，其他不常用屬性請(qǐng)查看其他人博客！

@Api

@Api

@Api : 
    位置：用在請(qǐng)求的類上，例如Controller，
    作用：說(shuō)明該類的主要作用。
    參數(shù)說(shuō)明：@Api("tags":"", "value":"", "description ":"")
        tags：說(shuō)明該類的作用，參數(shù)是個(gè)數(shù)組，可以填多個(gè)。
        value="該參數(shù)沒(méi)什么意義，在UI界面上不顯示，所以不用配置"
        description = "用戶基本信息操作"

代碼示例如下：

@RestController
@RequestMapping("/swagger")
@Api(tags = "用戶管理")
@Slf4j
public class SwaggerController {}

網(wǎng)站效果展示：

@ApiOperation

@ApiOperation

@ApiOperation：
    位置：用在請(qǐng)求方法上
    作用：說(shuō)明方法的用途、作用
    參數(shù)說(shuō)明：@ApiOperation("value":"", "notes":"", "tags ":"")
        value="方法的用途和作用"
        notes="方法的注意事項(xiàng)和備注"			
        tags：說(shuō)明該方法的作用， 參數(shù)是個(gè)數(shù)組，可以填多個(gè)。例如格式：tags={"作用1","作用2"}

代碼示例如下：

@GetMapping("/getList")
@ApiOperation(value = "分頁(yè)查詢", notes = "分頁(yè)查詢的注意事項(xiàng)和備注", tags = {"說(shuō)明該方法的作用1,說(shuō)明該方法的作用2"})
public Response<PageResult<User>> getList(@RequestParam int pageNo, @RequestParam int pageSize){

網(wǎng)站效果展示：

@ApiImplicitParams

@ApiImplicitParams

@ApiImplicitParams: 
    位置：用在請(qǐng)求方法上
    作用：包含多@ApiImplicitParam，包含一組參數(shù)說(shuō)明。
    參數(shù)說(shuō)明：@ApiImplicitParams({@ApiImplicitParam("name":"", "value":"", "dataType":"", "paramType":"", "required":"")...})

@ApiImplicitParams: 
    位置：用在請(qǐng)求方法上
    作用：包含多@ApiImplicitParam，包含一組參數(shù)說(shuō)明。
    參數(shù)說(shuō)明：@ApiImplicitParams({@ApiImplicitParam("name":"", "value":"", "dataType":"", "paramType":"", "required":"")...})

代碼示例如下：

@GetMapping("/getList")
@ApiOperation(value = "分頁(yè)查詢", notes = "分頁(yè)查詢的注意事項(xiàng)和備注", tags = {"說(shuō)明該方法的作用1,說(shuō)明該方法的作用2"})
@ApiImplicitParams({
    @ApiImplicitParam(name = "pageNo", value = "當(dāng)前頁(yè)碼，從1開始", paramType = "query", required = true, dataType="int") ,
    @ApiImplicitParam(name = "pageSize", value = "每頁(yè)顯示記錄數(shù)", paramType = "query",required = true, dataType="int") ,
    })
public Response<PageResult<User>> getList(@RequestParam int pageNo, @RequestParam int pageSize){

@ApiImplicitParam

@ApiImplicitParam

@ApiImplicitParam：
    位置：用在請(qǐng)求方法上
    作用：用在@ApiImplicitParams注解中，指定一個(gè)請(qǐng)求參數(shù)的各個(gè)方面說(shuō)明
    參數(shù)說(shuō)明：@ApiImplicitParam("name":"", "value":"", "dataType":"", "paramType":"", "required":"")
        name="參數(shù)名稱"
        value="參數(shù)說(shuō)明"
        dataType="數(shù)據(jù)類型"，默認(rèn)String
        required=true 參數(shù)是否必選
        paramType="query" 表示參數(shù)放在哪里，查詢參數(shù)類型，這里有幾種形式：
            header --> 請(qǐng)求參數(shù)的獲?。篅RequestHeader，參數(shù)在 request headers 里邊提交
            query --> 請(qǐng)求參數(shù)的獲?。篅RequestParam，直接跟參數(shù)，完成自動(dòng)映射賦值
            path（用于 restful 接口）--> 請(qǐng)求參數(shù)的獲取：@PathVariable，以地址的形式提交數(shù)據(jù)
            body（不常用）--> 以流的形式提交 僅支持 POST
            form（不常用）--> 以 form 表單的形式提交 僅支持 POST

代碼示例如下：

@GetMapping("/getList")
@ApiOperation(value = "分頁(yè)查詢", notes = "分頁(yè)查詢的注意事項(xiàng)和備注", tags = {"說(shuō)明該方法的作用1,說(shuō)明該方法的作用2"})
@ApiImplicitParams({
    @ApiImplicitParam(name = "pageNo", value = "當(dāng)前頁(yè)碼，從1開始", paramType = "query", required = true, dataType="int") ,
    @ApiImplicitParam(name = "pageSize", value = "每頁(yè)顯示記錄數(shù)", paramType = "query",required = true, dataType="int") ,
    })
public Response<PageResult<User>> getList(@RequestParam int pageNo, @RequestParam int pageSize){

網(wǎng)站效果展示：

@ApiResponses

@ApiResponses

@ApiResponses：用在請(qǐng)求的方法上，表示一組響應(yīng)

代碼示例如下：

@GetMapping("/getList")
@ApiResponses({
     @ApiResponse(code=400,message="請(qǐng)求參數(shù)及格式不對(duì)"),
      @ApiResponse(code=404,message="請(qǐng)求路徑?jīng)]有或頁(yè)面跳轉(zhuǎn)路徑不對(duì)")
    })
public Response<PageResult<User>> getList(@RequestParam int pageNo, @RequestParam int pageSize){

@ApiResponse

@ApiResponse

@ApiResponse：用在@ApiResponses中，一般用于表達(dá)一個(gè)錯(cuò)誤的響應(yīng)信息
    code：數(shù)字，例如400
    message：信息，例如"請(qǐng)求參數(shù)沒(méi)填好"
    response：拋出異常的類

代碼示例如下：

@GetMapping("/getList")
@ApiResponses({
    @ApiResponse(code=400,message="請(qǐng)求參數(shù)及格式不對(duì)"),
    @ApiResponse(code=404,message="請(qǐng)求路徑?jīng)]有或頁(yè)面跳轉(zhuǎn)路徑不對(duì)")
})
public Response<PageResult<User>> getList(@RequestParam int pageNo, @RequestParam int pageSize){

網(wǎng)站效果展示：

@ApiModel

@ApiModel

@ApiModel：
    位置：用在返回對(duì)象類上
    作用：描述一個(gè)Model的信息（一般用在請(qǐng)求參數(shù)無(wú)法使用@ApiImplicitParam注解進(jìn)行描述的時(shí)候）
    參數(shù)說(shuō)明：@ApiModel("description":"")
        description="描述實(shí)體的作用"

代碼示例如下：

package com.swagger.bean;

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

@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(description= "返回響應(yīng)數(shù)據(jù)")
public class User {
    @ApiModelProperty(name = "id", value = "用戶ID")
    private Integer id;
    //姓名
    @ApiModelProperty(name = "name", value = "用戶姓名")
    private String name;
    //密碼
    @ApiModelProperty(name = "password", value = "用戶密碼")
    private String password;
}

@ApiModelProperty

@ApiModelProperty

@ApiModelProperty：
    位置：用在屬性上
    作用：描述一個(gè)model的屬性
    參數(shù)說(shuō)明：@ApiModelProperty("value":"", "name":"", "required":"")
        value="參數(shù)說(shuō)明" 描述參數(shù)的意義
        name="參數(shù)名稱" 參數(shù)的變量名
        required=true 參數(shù)是否必選

代碼示例如下：

package com.swagger.bean;

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

@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(description= "返回響應(yīng)數(shù)據(jù)")
public class User {
    @ApiModelProperty(name = "id", value = "用戶ID")
    private Integer id;
    //姓名
    @ApiModelProperty(name = "name", value = "用戶姓名")
    private String name;
    //密碼
    @ApiModelProperty(name = "password", value = "用戶密碼")
    private String password;
}

網(wǎng)站效果展示：

@ApiParam

@ApiParam

@ApiParam：
    位置：用在請(qǐng)求方法、參數(shù)上
    作用：對(duì)參數(shù)使用說(shuō)明（如：說(shuō)明 或是否必填等）
    參數(shù)說(shuō)明：@ApiParam("value":"", "name":"", "required":"")
        value="參數(shù)說(shuō)明" 描述參數(shù)的意義
        name="參數(shù)名稱" 參數(shù)的變量名
        required=true 參數(shù)是否必選

代碼示例如下：

@PostMapping("/post")
@ApiOperation(value = "新增用戶", notes = "演示json參數(shù)是否接受成功")
public Response postTest(@ApiParam(name = "user", value = "接收傳遞給后端接口的user對(duì)象參數(shù)") @RequestBody User user) {

網(wǎng)站效果展示：

@ApiIgnore

@ApiIgnore

@ApiIgnore:
    位置：用在類，方法，參數(shù)
    作用：表示這個(gè)方法或者類被忽略，也就是在http://ip:port/swagger-ui.html上不顯示
    參數(shù)說(shuō)明：無(wú)

代碼示例如下： ???????

@ApiIgnore
@PutMapping("/update2")
@ApiOperation(value = "修改用戶2", notes = "演示json參數(shù)是否接受成功")
public Response updateTest2(@ApiParam(name = "user", value = "接收傳遞給后端接口的user對(duì)象參數(shù)") @RequestBody User user) {

具體使用詳情請(qǐng)看：Swagger中@ApiIgnore注解的使用

網(wǎng)站效果展示：

五、案例準(zhǔn)備工作

0.項(xiàng)目目錄

1.pom依賴

<dependencies>
    <!--解決@RestController注解爆紅-->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
        <version>2.6.3</version>
    </dependency>

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

    <!--Swagger版本-->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-boot-starter</artifactId>
        <version>3.0.0</version>
    </dependency>
</dependencies>

2.創(chuàng)建SwaggerConfig

package com.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.oas.annotations.EnableOpenApi;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * Swagger配置
 */
@Configuration
@EnableOpenApi //@EnableOpenApi用于開啟Swagger在 Spring Boot，可放在啟動(dòng)類上，也可放在這里，
public class SwaggerConfig {
    /**
     * 配置Swagger的Docket的bean實(shí)例
     */
    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.OAS_30)
                //(常用) groupName：分組
                .groupName("標(biāo)準(zhǔn)接口")
                .apiInfo(apiInfo())
                //(常用) select：通過(guò)select()函數(shù)返回一個(gè)ApiSelectorBuilder實(shí)例,用來(lái)控制哪些接口暴露給Swagger來(lái)展現(xiàn)
                .select()
                //
                /**
                 * (常用) apis：過(guò)濾規(guī)則，可以自定義指定哪些接口生成文檔
                 *  RequestHandlerSelectors:配置要掃描接口的方式
                 *       basePackage:指定要掃描的包
                 *       any:掃面全部
                 *       none:不掃描
                 *       withClassAnnotation:掃描類上的注解(參數(shù)是類上注解的class對(duì)象)
                 *       withMethodAnnotation:掃描方法上的注解(參數(shù)是方法上的注解的class對(duì)象)
                 */
                .apis(RequestHandlerSelectors.basePackage("com.swagger.controller"))
                //(常用) apis：加了ApiOperation注解的類，生成接口文檔
//              .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                /**
                 * (常用) paths：過(guò)濾路徑
                 *  PathSelectors:配置過(guò)濾的路徑
                 *      any:過(guò)濾全部路徑
                 *      none:不過(guò)濾路徑
                 *      ant:過(guò)濾指定路徑:按照按照Spring的AntPathMatcher提供的match方法進(jìn)行匹配
                 *      regex:過(guò)濾指定路徑:按照String的matches方法進(jìn)行匹配
                 */
                .paths(PathSelectors.any())
                //(已淘汰）所有接口統(tǒng)一定義響應(yīng)信息
//              .build().globalResponseMessage();
                .build();
    }

    /**
     * 配置文檔描述
     * 訪問(wèn)地址：http://ip:port/swagger-ui.html
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //文檔標(biāo)題
                .title("標(biāo)題：Spring Boot中使用Swagger3.0.0版本構(gòu)建RESTful APIs")
                //文檔描述
                .description("描述：用戶列表的CRUD")
                //團(tuán)隊(duì)鏈接
                .termsOfServiceUrl("https://blog.csdn.net/a924382407/article/details/127842503")
                //聯(lián)系人信息
                .contact(new Contact("劉大貓", "https://blog.csdn.net/a924382407/article/details/127842503", "ldz924382407@163.com"))
                //API 版本
                .version("1.0")
                .build();
    }
}

3.配置文件application.yml

# 端口號(hào)
server:
  port: 8016

# 設(shè)置SpringMVC的路徑匹配策略
spring:
  mvc:
    pathmatch:
      matching-strategy: ant_path_matcher

4.實(shí)體bean

package com.swagger.bean;

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

/**
 * @Author 211145187
 * @Date 2022/2/23 09:32
 **/
@Data
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(description= "返回響應(yīng)數(shù)據(jù)")
public class User {
    @ApiModelProperty(name = "id", value = "用戶ID")
    private Integer id;
    //姓名
    @ApiModelProperty(name = "name", value = "用戶姓名")
    private String name;
    //密碼
    @ApiModelProperty(name = "password", value = "用戶密碼")
    private String password;
}

5.后端接口SwaggerController

package com.swagger.controller;

import com.swagger.bean.User;
import com.swagger.response.PageResult;
import com.swagger.response.Response;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
import springfox.documentation.annotations.ApiIgnore;

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

/**
 * 使用swagger,用于生成、描述、調(diào)用和可視化 RESTful 風(fēng)格的 Web 服務(wù)
 * @Author 211145187
 * @Date 2022/9/19 16:31
 **/
@RestController
@RequestMapping("/swagger")
@Api(tags = "用戶管理")
@Slf4j
public class SwaggerController {

    @GetMapping("/getList")
    @ApiOperation(value = "分頁(yè)查詢", notes = "分頁(yè)查詢的注意事項(xiàng)和備注", tags = {"說(shuō)明該方法的作用1,說(shuō)明該方法的作用2"})
    @ApiImplicitParams({
            @ApiImplicitParam(name = "pageNo", value = "當(dāng)前頁(yè)碼，從1開始", paramType = "query", required = true, dataType="int") ,
            @ApiImplicitParam(name = "pageSize", value = "每頁(yè)顯示記錄數(shù)", paramType = "query",required = true, dataType="int") ,
    })
    @ApiResponses({
            @ApiResponse(code=400,message="請(qǐng)求參數(shù)及格式不對(duì)"),
            @ApiResponse(code=404,message="請(qǐng)求路徑?jīng)]有或頁(yè)面跳轉(zhuǎn)路徑不對(duì)")
    })
    public Response<PageResult<User>> getList(@RequestParam int pageNo, @RequestParam int pageSize){
        log.info("-getList-pageNo:{},pageSize:{}", pageNo, pageSize);
        List list = new ArrayList();
        list.add(new User(1, "tom", "tom"));
        list.add(new User(2, "jerry", "jerry"));
        PageResult pageResult = new PageResult();
        pageResult.setPageNum(pageNo);
        pageResult.setPageSize(pageSize);
        pageResult.setTotalPage(1);
        pageResult.setTotalCount(2);
        pageResult.setList(list);
        return Response.success(pageResult);
    }

    @PostMapping("/post")
    @ApiOperation(value = "新增用戶", notes = "演示json參數(shù)是否接受成功")
    public Response postTest(@ApiParam(name = "user", value = "接收傳遞給后端接口的user對(duì)象參數(shù)") @RequestBody User user) {
        log.info("-postTest-user:{}", user);
        return Response.success(user);
    }

    @PutMapping("/update")
    @ApiOperation(value = "修改用戶", notes = "演示json參數(shù)是否接受成功")
    public Response updateTest(@ApiParam(name = "user", value = "接收傳遞給后端接口的user對(duì)象參數(shù)") @RequestBody User user) {
        log.info("-postTest-user:{}", user);
        return Response.success(user);
    }

    @ApiIgnore
    @PutMapping("/update2")
    @ApiOperation(value = "修改用戶2", notes = "演示json參數(shù)是否接受成功")
    public Response updateTest2(@ApiParam(name = "user", value = "接收傳遞給后端接口的user對(duì)象參數(shù)") @RequestBody User user) {
        log.info("-postTest-user:{}", user);
        return Response.success(user);
    }

    @DeleteMapping("/delete/{id}")
    @ApiOperation(value = "刪除用戶", notes = "演示json參數(shù)是否接受成功")
    public Response deleteTest(@ApiParam(name = "id", value = "接收的參數(shù)id") @PathVariable Integer id) {
        log.info("-deleteTest-id:{}", id);
        return Response.success(id);
    }
}

6.返回對(duì)象Response介紹

SpringBoot ResponseBody返回值處理的實(shí)現(xiàn)

7.啟動(dòng)類

package com.swagger;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

/**
 * 使用swagger,用于生成、描述、調(diào)用和可視化 RESTful 風(fēng)格的 Web 服務(wù)
 * @Author 211145187
 * @Date 2022/9/20 14:33
 **/
@SpringBootApplication
public class SwaggerApplication {
    public static void main(String[] args) {
        SpringApplication.run(SwaggerApplication.class, args);
    }
}

六、運(yùn)行結(jié)果展示

登錄網(wǎng)址：http://localhost:8016/swagger-ui/index.html#/ 即可打開如下圖的網(wǎng)站

七、注意事項(xiàng)說(shuō)明

1.@ApiOperation注解的tags屬性盡量少用，因?yàn)閠ags屬性會(huì)對(duì)接口重新分類，導(dǎo)致登錄swagger-ui查看接口不清晰，具體如圖，比如我只有一個(gè)Controller里面包含4個(gè)方法，按常理應(yīng)該只有一個(gè)”用戶管理“的接口說(shuō)明，如果我使用tags屬性，那么下方會(huì)多出一個(gè)tags屬性標(biāo)識(shí)過(guò)的重復(fù)的的接口說(shuō)明（說(shuō)白了就是有重復(fù)的顯示，感覺(jué)不直觀）。

2.SwaggerConfig中無(wú)論是Docket屬性還是ApiInfoBuilder屬性、以及注解中屬性都有很多，該案例只使用常用的幾個(gè)屬性，想了解其他屬性請(qǐng)查看其他人博客了解即可。

3.Swagger2.x版本中開啟Swagger在SpringBoot項(xiàng)目的啟動(dòng)類或配置類中添加@EnableSwagger2，而Swagger3.0.0版本中開啟Swagger在SpringBoot項(xiàng)目的啟動(dòng)類或配置類中添加@EnableOpenApi

4.ApiInfo 基本信息參數(shù)介紹，可以看到，它提供了 8 個(gè)可以配置屬性，根據(jù)名字也能猜出其中的意思。

version：API 版本
title：文檔標(biāo)題
description：文檔描述
termsOfServiceUrl：團(tuán)隊(duì)鏈接
license：許可
licenseUrl：許可鏈接
contact：聯(lián)系人信息
vendorExtensions：擴(kuò)展信息

5.問(wèn)題：注解@ApiParam和@ApiImplicitParams都是作用在方法上，區(qū)別是啥？
答案：他兩互相都可以互為替代品，即描述參數(shù)用@ApiParam和@ApiImplicitParams都可以，只不過(guò)@ApiImplicitParams要和@ApiImplicitParam搭配使用。

八、報(bào)錯(cuò)場(chǎng)景說(shuō)明

錯(cuò)誤場(chǎng)景1：org.springframework.context.ApplicationContextException: Failed to start bean ‘documentationPluginsBootstrapper’; nested exception is java.lang.NullPointerException

org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException
	at org.springframework.context.support.DefaultLifecycleProcessor.doStart(DefaultLifecycleProcessor.java:181) ~[spring-context-5.3.15.jar:5.3.15]
	at org.springframework.context.support.DefaultLifecycleProcessor.access$200(DefaultLifecycleProcessor.java:54) ~[spring-context-5.3.15.jar:5.3.15]
	at org.springframework.context.support.DefaultLifecycleProcessor$LifecycleGroup.start(DefaultLifecycleProcessor.java:356) ~[spring-context-5.3.15.jar:5.3.15]
	at java.lang.Iterable.forEach(Iterable.java:75) ~[na:1.8.0_71]
	at org.springframework.context.support.DefaultLifecycleProcessor.startBeans(DefaultLifecycleProcessor.java:155) ~[spring-context-5.3.15.jar:5.3.15]
	at org.springframework.context.support.DefaultLifecycleProcessor.onRefresh(DefaultLifecycleProcessor.java:123) ~[spring-context-5.3.15.jar:5.3.15]
	at org.springframework.context.support.AbstractApplicationContext.finishRefresh(AbstractApplicationContext.java:935) ~[spring-context-5.3.15.jar:5.3.15]
	at org.springframework.context.support.AbstractApplicationContext.refresh(AbstractApplicationContext.java:586) ~[spring-context-5.3.15.jar:5.3.15]
	at org.springframework.boot.web.servlet.context.ServletWebServerApplicationContext.refresh(ServletWebServerApplicationContext.java:145) ~[spring-boot-2.6.3.jar:2.6.3]
	at org.springframework.boot.SpringApplication.refresh(SpringApplication.java:732) [spring-boot-2.6.3.jar:2.6.3]
	at org.springframework.boot.SpringApplication.refreshContext(SpringApplication.java:414) [spring-boot-2.6.3.jar:2.6.3]
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:302) [spring-boot-2.6.3.jar:2.6.3]
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:1303) [spring-boot-2.6.3.jar:2.6.3]
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:1292) [spring-boot-2.6.3.jar:2.6.3]
	at com.swagger.SwaggerApplication.main(SwaggerApplication.java:14) [classes/:na]
Caused by: java.lang.NullPointerException: null
	at springfox.documentation.spring.web.WebMvcPatternsRequestConditionWrapper.getPatterns(WebMvcPatternsRequestConditionWrapper.java:56) ~[springfox-spring-webmvc-3.0.0.jar:3.0.0]
	at springfox.documentation.RequestHandler.sortedPaths(RequestHandler.java:113) ~[springfox-core-3.0.0.jar:3.0.0]
	at springfox.documentation.spi.service.contexts.Orderings.lambda$byPatternsCondition$3(Orderings.java:89) ~[springfox-spi-3.0.0.jar:3.0.0]
	at java.util.Comparator.lambda$comparing$77a9974f$1(Comparator.java:469) ~[na:1.8.0_71]
	at java.util.TimSort.countRunAndMakeAscending(TimSort.java:355) ~[na:1.8.0_71]
	at java.util.TimSort.sort(TimSort.java:220) ~[na:1.8.0_71]
	at java.util.Arrays.sort(Arrays.java:1512) ~[na:1.8.0_71]
	at java.util.ArrayList.sort(ArrayList.java:1454) ~[na:1.8.0_71]
	at java.util.stream.SortedOps$RefSortingSink.end(SortedOps.java:387) ~[na:1.8.0_71]
	at java.util.stream.Sink$ChainedReference.end(Sink.java:258) ~[na:1.8.0_71]
	at java.util.stream.Sink$ChainedReference.end(Sink.java:258) ~[na:1.8.0_71]
	at java.util.stream.Sink$ChainedReference.end(Sink.java:258) ~[na:1.8.0_71]
	at java.util.stream.Sink$ChainedReference.end(Sink.java:258) ~[na:1.8.0_71]
	at java.util.stream.AbstractPipeline.copyInto(AbstractPipeline.java:482) ~[na:1.8.0_71]
	at java.util.stream.AbstractPipeline.wrapAndCopyInto(AbstractPipeline.java:471) ~[na:1.8.0_71]
	at java.util.stream.ReduceOps$ReduceOp.evaluateSequential(ReduceOps.java:708) ~[na:1.8.0_71]
	at java.util.stream.AbstractPipeline.evaluate(AbstractPipeline.java:234) ~[na:1.8.0_71]
	at java.util.stream.ReferencePipeline.collect(ReferencePipeline.java:499) ~[na:1.8.0_71]
	at springfox.documentation.spring.web.plugins.WebMvcRequestHandlerProvider.requestHandlers(WebMvcRequestHandlerProvider.java:81) ~[springfox-spring-webmvc-3.0.0.jar:3.0.0]
	at java.util.stream.ReferencePipeline$3$1.accept(ReferencePipeline.java:193) ~[na:1.8.0_71]
	at java.util.ArrayList$ArrayListSpliterator.forEachRemaining(ArrayList.java:1374) ~[na:1.8.0_71]
	at java.util.stream.AbstractPipeline.copyInto(AbstractPipeline.java:481) ~[na:1.8.0_71]
	at java.util.stream.AbstractPipeline.wrapAndCopyInto(AbstractPipeline.java:471) ~[na:1.8.0_71]
	at java.util.stream.ReduceOps$ReduceOp.evaluateSequential(ReduceOps.java:708) ~[na:1.8.0_71]
	at java.util.stream.AbstractPipeline.evaluate(AbstractPipeline.java:234) ~[na:1.8.0_71]
	at java.util.stream.ReferencePipeline.collect(ReferencePipeline.java:499) ~[na:1.8.0_71]
	at springfox.documentation.spring.web.plugins.AbstractDocumentationPluginsBootstrapper.withDefaults(AbstractDocumentationPluginsBootstrapper.java:107) ~[springfox-spring-web-3.0.0.jar:3.0.0]
	at springfox.documentation.spring.web.plugins.AbstractDocumentationPluginsBootstrapper.buildContext(AbstractDocumentationPluginsBootstrapper.java:91) ~[springfox-spring-web-3.0.0.jar:3.0.0]
	at springfox.documentation.spring.web.plugins.AbstractDocumentationPluginsBootstrapper.bootstrapDocumentationPlugins(AbstractDocumentationPluginsBootstrapper.java:82) ~[springfox-spring-web-3.0.0.jar:3.0.0]
	at springfox.documentation.spring.web.plugins.DocumentationPluginsBootstrapper.start(DocumentationPluginsBootstrapper.java:100) ~[springfox-spring-web-3.0.0.jar:3.0.0]
	at org.springframework.context.support.DefaultLifecycleProcessor.doStart(DefaultLifecycleProcessor.java:178) ~[spring-context-5.3.15.jar:5.3.15]
	... 14 common frames omitted

錯(cuò)誤原因：SpinrgBoot版本過(guò)高導(dǎo)致，比如我的SpringBoot版本2.7.3，它使用的Spring版本5.3.22 ，而Spring5.x版本中SpringMVC 默認(rèn)路徑匹配策略從AntPathMatcher 更改為PathPatternParser

解決方案：針對(duì)原因2，解決辦法是切換回原先的AntPathMatcher，即在application.yml中配置spring:mvc:pathmatch:matching-strategy: ant_path_matcher

也可以查看其他人的博客了解詳情：Docker啟動(dòng)失敗報(bào)錯(cuò)Failed to start Docker Application Container Engine的解決辦法

到此這篇關(guān)于Spring Boot中使用Swagger3.0.0版本構(gòu)建RESTful APIs的文章就介紹到這了,更多相關(guān)Spring Boot使用Swagger構(gòu)建RESTful APIs內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

您可能感興趣的文章:

最新国产好看的视频,伊人天堂AV在线,国产Aaaaaa视频,蜜臀视频在线观看一区,人妻av色图,密臀久久久精品影片,青青视频免费观看毛片,久草在线观看视,国产三级精品色情在线

Spring?Boot中使用Swagger3.0.0版本構(gòu)建RESTful?APIs的方法

目錄

一、項(xiàng)目描述

二、簡(jiǎn)介

三、Swagger2.X和Swagger3.0.0 的對(duì)比

1）SpringFox 2.x 發(fā)布

2）SpringFox 3.0.0 發(fā)布

3）swagger3.0 與2.xx配置差異：

四、注解說(shuō)明

@Api

@ApiOperation

@ApiImplicitParams

@ApiImplicitParam

@ApiResponses

@ApiModel

@ApiModelProperty

@ApiIgnore

五、案例準(zhǔn)備工作

0.項(xiàng)目目錄

1.pom依賴

2.創(chuàng)建SwaggerConfig

3.配置文件application.yml

4.實(shí)體bean

5.后端接口SwaggerController

6.返回對(duì)象Response介紹

7.啟動(dòng)類

六、運(yùn)行結(jié)果展示

七、注意事項(xiàng)說(shuō)明

八、報(bào)錯(cuò)場(chǎng)景說(shuō)明

相關(guān)文章

最新評(píng)論

大家感興趣的內(nèi)容

最近更新的內(nèi)容

常用在線小工具

最新国产好看的视频,伊人天堂AV在线,国产Aaaaaa视频,蜜臀视频在线观看一区,人妻av色图,密臀久久久精品影片,青青视频免费观看毛片,久草在线观看视,国产三级精品色情在线

Spring?Boot中使用Swagger3.0.0版本構(gòu)建RESTful?APIs的方法

目錄

一、項(xiàng)目描述

二、簡(jiǎn)介

三、Swagger2.X和Swagger3.0.0 的對(duì)比

1）SpringFox 2.x 發(fā)布

2）SpringFox 3.0.0 發(fā)布

3）swagger3.0 與2.xx配置差異：

四、注解說(shuō)明

@Api

@ApiOperation

@ApiImplicitParams

@ApiImplicitParam

@ApiResponses

@ApiModel

@ApiModelProperty

@ApiIgnore

五、案例準(zhǔn)備工作

0.項(xiàng)目目錄

1.pom依賴

2.創(chuàng)建SwaggerConfig

3.配置文件application.yml

4.實(shí)體bean

5.后端接口SwaggerController

6.返回對(duì)象Response介紹

7.啟動(dòng)類

六、運(yùn)行結(jié)果展示

七、注意事項(xiàng)說(shuō)明

八、報(bào)錯(cuò)場(chǎng)景說(shuō)明

相關(guān)文章

最新評(píng)論

大家感興趣的內(nèi)容

最近更新的內(nèi)容

常用在線小工具

二、簡(jiǎn)介

四、注解說(shuō)明

五、案例準(zhǔn)備工作

七、注意事項(xiàng)說(shuō)明