SpringBoot整合介面管理工具Swagger怎麼使用

一、Swagger簡介

Swagger 是一系列 RESTful API 的工具，透過 Swagger 可以獲得專案的⼀種互動式文檔，客戶端 SDK 的自動生成等功能。

Swagger 的目標是為REST APIs 定義一個標準的、與語⾔言無關的接口，使人和計算機在看不到源碼或者看不到文檔或者不能通過網絡流量檢測的情況下，能發現並理解各種服務的功能。當服務透過 Swagger 定義，消費者就能與遠端的服務互動透過少量的實現邏輯。

二、Springboot整合swagger

使用Spring Boot 整合Swagger 的理念是，使用註解來標記需要在API 文件中展示的訊息，Swagger 會根據專案中標記的註解來產生對應的API 文件。 Swagger 被號稱世界上最受歡迎的 API 工具，它提供了 API 管理的全套解決方案，API 文件管理需要考慮的因素基本上都包含，這裡將講解最常用的客製化內容。

1、新增swagger座標

Spring Boot 整合 Swagger 3 很簡單，需要引入依賴並做基礎配置即可。

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

2、Swagger Helloword 實作

2.1、建立springboot專案

在啟動類別上加上@EnableOpenApi 註解啟用swagger api文件功能

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.oas.annotations.EnableOpenApi;

@SpringBootApplication
@EnableOpenApi  //启动swagger api文档注解
public class SpringBootWithSwaggerApplication {
    public static void main(String[] args) {
        SpringApplication.run(SpringBootWithSwaggerApplication.class, args);
    }

}

# 2.2、寫一個介面

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author 阿水
 * @create 2023-04-11 9:54
 */
@RestController()
public class SwaggerController {
    @GetMapping ("hello")
    public String hello(String params) {
        return "hello swagger"+" param为:"+params;
    }
}

2.3、存取位址

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

##三、常用的設定註解

Swagger 透過註解表明此介面會產生文檔，包括介面名稱、請求方法、參數、返回訊息等

1、

Api 註解和 ApiOperation 註解

• @Api

#使用在類別上，表示是swagger資源，@API擁有兩個屬性:value 、tags。

產生的api文檔會根據tags分類，直白的說就是這個controller中的所有介面產生的介面文件都會在tags這個list下；tags如果有多個值，會產生多個list，每個list都顯示所有介面

value的作用類似tags,但是不能有多個值

语法:
  @Api(tags = "用户操作")
  或
  @Api(tags = {"用户操作","用户操作2"})

• ##@ApiOperation

使用於在方法上，表示一個http請求的操作

语法:
    @ApiOperation(value = "", 
                  notes = "", 
                  response = )
属性说明：
  value：方法说明标题
  notes：方法详细描述
  response：方法返回值类型

案例：使用@Api和@ApiOperation產生api文檔

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author 阿水
 * @create 2023-04-11 9:54
 */
@RestController()
@Api(tags = {"操作用户"})
public class SwaggerController {
    @GetMapping ("hello")
    @ApiOperation(value = "swagger请求",notes = "阿水的第一个swagger请求",response = String.class)
    public String hello(String params) {
        return "hello swagger"+" param为:"+params;
    }
}

2、

ApiImplicitParams

 註解和 ApiImplicitParam

@ApiImplicitParams

 註解和 #@ApiImplicitParam用於對方法中的非物件綁定到簡單類型時使用。)進行說明

语法:
@ApiImplicitParams(value = {
     @ApiImplicitParam(name="", value = "", type = "", required = true, paramType = "", defaultValue  = "")
})

属性说明：
    name:形参名称
    value:形参的说明文字
    type:形参类型
    required:该参数是否必须  true|false
    paramType: 用于描述参数是以何种方式传递到 Controller 的，它的值常见有： path, query, body 和 header 
        path 表示参数是『嵌在』路径中的，它和 @PathVariable 参数注解遥相呼应；
    	query 表示参数是以 query string 的形式传递到后台的（无论是 get 请求携带在 url 中，还是 post 请求携带在请求体中），它和 @RequestParam 参数注解遥相呼应；
    	header 表示参数是『藏在』请求头中传递到后台的，它和 @RequestHeader 参数注解遥相呼应的。
    	form 不常用.
    defaultValue :参数默认值

注意：@ApiImplicitParam 的name 屬性要和@RequestParam 或@PathVariable 的value 遙相呼應。

案例：使用@ApiImplicitParams註解和@ApiImplicitParam 對方法參數進行說明

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.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @author 阿水
 * @create 2023-04-11 9:54
 */
@RestController()
@Api(tags = {"操作用户"})
public class SwaggerController {
    @GetMapping ("hello")
    @ApiOperation(value = "swagger请求",notes = "阿水的第一个swagger请求",response = String.class)
    @ApiImplicitParams(value ={
            @ApiImplicitParam(name="param1",
                    value = "参数名1",
                    type = "String",
                    required = true,
                    paramType = "query",
                    defaultValue  = "阿水所想的默认值1" ),
            @ApiImplicitParam(name="param2",
                    value = "参数名2",
                    type = "String",
                    required = true,
                    paramType = "query",
                    defaultValue  = "阿水所想的默认值2" )
    })
    public String hello(String param1,String param2) {
        return "hello swagger"+" param1为:"+param1+"param2为"+param2;
    }
}

3、ApiModel註解和ApiModelProperty

#####################################################################################################################1 ####@ApiModel######用在實體類別上，表示對類別進行說明，用於實體類別中的參數接收說明。 #########

@ApiModel("用户类")
@Data
public class Users {

    @ApiModelProperty(value = "编码：主键")
    private Integer id;

    @ApiModelProperty(value = "用户名")
    private String username;

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

}

###4、ApiResponse 和ApiResponses######@ApiResponses 註解和@ApiResponse 標註在Controller 的方法上，用來描述HTTP 請求的回應###

/**
     * 添加用户
     *
     * @param user
     * @return
     */
    @PostMapping("/add")
    @ApiOperation(value = "添加用户",notes = "添加用户信息",response = ResponseResult.class)
    @ApiResponses({ @ApiResponse(code = 200, message = "添加成功", response = ResponseResult.class),
            	    @ApiResponse(code = 500, message = "添加失败", response = ResponseResult.class) })
    public ResponseResult<Void> addUser(@RequestBody User user) {
        //获得生成的加密盐
        user.setSalt(SaltUtils.getSalt());
        int n = userService.addUser(user);
        if (n > 0) {
            return new ResponseResult<Void>(200, "添加成功");
        }
        return new ResponseResult<Void>(500, "添加失败");
    }

## #5、建立SwaggerConfig 設定類別######在SwaggerConfig 中加入兩個方法：（其中一個方法是為另一個方法作輔助的準備工作）#####api()方法使用@Bean，在啟動時初始化，返回實例Docket（Swagger API 摘要物件），這裡需要注意的是.apis(RequestHandlerSelectors.basePackage("xxx.yyy.zzz")) 指定需要掃描的包路路徑，只有此路徑下的Controller類別才會自動產生Swagger 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.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * Swagger配置类
 */
@Configuration  //项目启动时加载此类
public class SwaggerConfig {
    @Bean
    public Docket api(){
        return new Docket(DocumentationType.OAS_30)
                .apiInfo(apiInfo())
                .select()
                // 此处自行修改为自己的 Controller 包路径。
                .apis(RequestHandlerSelectors.basePackage("com.lps.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    public ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                .title("阿水的项目接口文挡")
                .description("阿水的 Project Swagger2 UserService Interface")  //说明信息
                .termsOfServiceUrl("http://localhost:8080/swagger-ui/index.html") //文档生成的主页地址
                .version("1.0")  //文档版本
                .build();
    }
}

###apiInfo()方法配置相對重要一些，主要配置頁面展示的基本資訊包括，標題、描述、版本、服務條款等，查看ApiInfo 類別的源碼還會發現支援license 等更多的配置######四、springsecurity整合swagger######4.1，設定放行的位址###

  http.authorizeRequests().antMatchers( "/swagger-ui.html",
                "/swagger-ui/*",
                "/swagger-resources/**",
                "/v2/api-docs",
                "/v3/api-docs",
                "/webjars/**").permitAll()
                .anyRequest().authenticated();

###4.2，取代UI######上面的整個過程已經完成了，但是生成的介面文件的頁面，其實很多人不太喜歡，覺得不太符合國人的使用習慣，所有又有一些大神，提供了其他的UI測試頁面。這個頁面的使用還是比較廣泛的。 ######匯入以下依賴、重新啟動工程後存取位址：http://localhost:8080/doc.html###

	<dependency>
        <groupId>com.github.xiaoymin</groupId>
        <artifactId>swagger-bootstrap-ui</artifactId>
        <version>1.9.6</version>
    </dependency>

#########

以上是SpringBoot整合介面管理工具Swagger怎麼使用的詳細內容。更多資訊請關注PHP中文網其他相關文章！