Swagger3簡介

swagger官網(wǎng)：傳送門
swagger是一個Api框架，就是一個工具，就比如我們可以使用postman測試接口一樣，swagger主要作用是生成RESTFUL接口的文檔并且可以提供功能測試；
通過swagger可以獲取項目的api結(jié)果，生成清晰的api文檔，并可以進行一些自動化測試

Swagger的組成

1. Swagger-tools:提供各種與Swagger進行集成和交互的工具。例如模式檢驗、Swagger 1.2文檔轉(zhuǎn)換成Swagger2.0文檔等功能。
2. Swagger-core:用于Java/Scala的的Swagger實現(xiàn)。與JAX-RS(Jersey、Resteasy、CXF…)、Servlets和Play框架進行集成。
3. Swagger-js: 用于JavaScript的Swagger實現(xiàn)。
4. Swagger-node-express: Swagger模塊，用于node.js的Express web應用框架。
5. Swagger-ui：一個無依賴的HTML、JS和CSS集合，可以為Swagger兼容API動態(tài)生成優(yōu)雅文檔。
6. Swagger-codegen：一個模板驅(qū)動引擎，通過分析用戶Swagger資源聲明以各種語言生成客戶端代碼。

Swagger的Springboot配置

maven添加依賴

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

創(chuàng)建swagger的配置類

import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;
import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
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.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spi.service.contexts.SecurityContext;
import springfox.documentation.spring.web.plugins.Docket;
 
import java.util.ArrayList;
import java.util.HashSet;
import java.util.List;
import java.util.Set;
 
/**
 * @author rongrong
 * @version 1.0
 * @description Swagger3配置
 * @date 2021/01/12 21:00
 */
@Configuration
@Profile({"dev", "local"})
@EnableOpenApi
@EnableSwaggerBootstrapUI
public class SwaggerConfig {
 
    /**
     * 是否開啟swagger配置，生產(chǎn)環(huán)境需關閉
     */
    /*    @Value("${swagger.enabled}")*/
    private boolean enable;
 
    /**
     * 創(chuàng)建API
     * http:IP:端口號/swagger-ui/index.html 原生地址
     * http:IP:端口號/doc.html bootStrap-UI地址
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.OAS_30).pathMapping("/")
                // 用來創(chuàng)建該API的基本信息，展示在文檔的頁面中（自定義展示的信息）
                /*.enable(enable)*/
                .apiInfo(apiInfo())
                // 設置哪些接口暴露給Swagger展示
                .select()
                // 掃描所有有注解的api，用這種方式更靈活
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // 掃描指定包中的swagger注解
                // .apis(RequestHandlerSelectors.basePackage("com.doctorcloud.product.web.controller"))
                // 掃描所有 .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.regex("(?!/ApiError.*).*"))
                .paths(PathSelectors.any())
                .build()
                // 支持的通訊協(xié)議集合
                .protocols(newHashSet("https", "http"))
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
 
    }
 
    /**
     * 支持的通訊協(xié)議集合
     *
     * @param type1
     * @param type2
     * @return
     */
    private Set<String> newHashSet(String type1, String type2) {
        Set<String> set = new HashSet<>();
        set.add(type1);
        set.add(type2);
        return set;
    }
 
    /**
     * 認證的安全上下文
     */
    private List<SecurityScheme> securitySchemes() {
        List<SecurityScheme> securitySchemes = new ArrayList<>();
        securitySchemes.add(new ApiKey("token", "token", "header"));
        return securitySchemes;
    }
 
    /**
     * 授權信息全局應用
     */
    private List<SecurityContext> securityContexts() {
        List<SecurityContext> securityContexts = new ArrayList<>();
        securityContexts.add(SecurityContext.builder()
                .securityReferences(defaultAuth())
                .forPaths(PathSelectors.any()).build());
        return securityContexts;
    }
 
     /**
     * 默認的安全上引用
     */
    private List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        List<SecurityReference> securityReferences = new ArrayList<>();
        securityReferences.add(new SecurityReference("Authorization", authorizationScopes));
        return securityReferences;
    }
 
 
    /**
     * 添加摘要信息
     * @return 返回ApiInfo對象
     */
    private ApiInfo apiInfo() {
        // 用ApiInfoBuilder進行定制
        return new ApiInfoBuilder()
                // 設置標題
                .title("接口文檔")
                // 服務條款
                .termsOfServiceUrl("NO terms of service")
                // 描述
                .description("這是SWAGGER_3生成的接口文檔")
                // 作者信息
                .contact(new Contact("rongrong", "https://www.cnblogs.com/longronglang/", "rongrong@gmail.com"))
                // 版本
                .version("版本號:V1.0")
                //協(xié)議
                .license("The Apache License")
                // 協(xié)議url
                .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
                .build();
    }
}

說明：
swagger3 摒棄了@EnableSwagger2這個注解，改成了@EnableOpenApi
swagger3 使用DocumentationType.OAS_30，swagger2版本這里是DocumentationType.SWAGGER_2

訪問路徑

http:IP:端口號/swagger-ui/index.html

application.yml環(huán)境配置

添加如下內(nèi)容，使得只在測試環(huán)境中才會有swagger，正式環(huán)境不顯示

spring:
  profiles:
    active: dev

API分組

Swagger默認是一個default分組：

可以通過分組來實現(xiàn)對不同API的分類，分組可以使用Docket的groupName屬性區(qū)分不同分組，并可以在Swagger中創(chuàng)建多個Docket的Bean實例來定義不同分組；

@Bean
public Docket docketCategory() {
    return new Docket(DocumentationType.OAS_30)
            .apiInfo(apiInfo())
            // 分組名稱
            .groupName("Category")
            .enable(true)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.yang.takeout.backend.controller"))
            // 過濾請求，只掃描請求以/category開頭的接口
            .paths(PathSelectors.ant("/category/**"))
            .build();
}

@Bean
public Docket docketEmployee() {
    return new Docket(DocumentationType.OAS_30)
            .apiInfo(apiInfo())
            // 分組名稱
            .groupName("Employee")
            .enable(true)
            .select()
            .apis(RequestHandlerSelectors.basePackage("com.yang.takeout.backend.controller"))
            // 過濾請求，只掃描請求以/employee開頭的接口
            .paths(PathSelectors.ant("/employee/**"))
            .build();
}

這里我只配置了兩個分組，可以多創(chuàng)建幾個Docket實例實現(xiàn)多分組；

分組效果：

Swagger常用注解

注解說明

用于類上

@Api：用在請求的類上，表示對類的說明
tags=“說明該類的作用，可以在UI界面上看到的注解”
value=“該參數(shù)沒什么意義，在UI界面上也看到，所以不需要配置”

用于方法上

@ApiOperation：用在請求的方法上，說明方法的用途、作用
value=“說明方法的用途、作用”
notes=“方法的備注說明”

@ApiImplicitParams：用在請求的方法上，表示一組參數(shù)說明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一個請求參數(shù)的各個方面
name：參數(shù)名
value：參數(shù)的漢字說明、解釋
required：參數(shù)是否必須傳
paramType：參數(shù)放在哪個地方
· header --> 請求參數(shù)的獲?。篅RequestHeader
· query --> 請求參數(shù)的獲?。篅RequestParam
· path（用于restful接口）–> 請求參數(shù)的獲?。篅PathVariable
· div（不常用）
· form（不常用）
dataType：參數(shù)類型，默認String，其它值dataType=“Integer”
defaultValue：參數(shù)的默認值

@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);
	}
}

@ApiResponses：用在請求的方法上，表示一組響應
@ApiResponse：用在@ApiResponses中，一般用于表達一個錯誤的響應信息
code：數(shù)字，例如400
message：信息，例如"請求參數(shù)沒填好"
response：拋出異常的類

@Api(tags="用戶模塊")
@Controller
public class UserController {

	@ApiOperation("獲取用戶信息")
	@ApiImplicitParams({
		@ApiImplicitParam(paramType="query", name="userId", dataType="String", required=true, value="用戶Id")
	}) 
	@ApiResponses({
		@ApiResponse(code = 200, message = "請求成功"),
		@ApiResponse(code = 400, message = "請求參數(shù)沒填好"),
		@ApiResponse(code = 404, message = "請求路徑?jīng)]有或頁面跳轉(zhuǎn)路徑不對")
	}) 
	@ResponseBody
	@RequestMapping("/list")
	public JsonResult list(@RequestParam String userId) {
		...
		return JsonResult.ok().put("page", pageUtil);
	}
}

用于對象類

@ApiModel：用于響應類上，表示一個返回響應數(shù)據(jù)的信息
（這種一般用在post創(chuàng)建的時候，使用@RequestBody這樣的場景，
請求參數(shù)無法使用@ApiImplicitParam注解進行描述的時候）
@ApiModelProperty：用在屬性上，描述響應類的屬性
value–字段說明
name–重寫屬性名字
dataType–重寫屬性類型
required–是否必填
example–舉例說明
hidden–隱藏

@ApiModel的功能：
1、當請求數(shù)據(jù)描述，即 @RequestBody 時， 用于封裝請求（包括數(shù)據(jù)的各種校驗）數(shù)據(jù)；
2、當響應值是對象時，即 @ResponseBody 時，用于返回值對象的描述。
當請求數(shù)據(jù)描述時， @RequestBody 時的使用

@ApiModel(description = "用戶登錄")
public class UserLoginVO implements Serializable {

	private static final long serialVersionUID = 1L;

	@ApiModelProperty(value = "用戶名",required=true)	
	private String username;

	@ApiModelProperty(value = "密碼",required=true)	
	private String password;
	
	// getter/setter省略
}

@Api(tags="用戶模塊")
@Controller
public class UserController {

	@ApiOperation(value = "用戶登錄", notes = "")	
	@PostMapping(value = "/login")
	public R login(@RequestBody UserLoginVO userLoginVO) {
		User user=userSerivce.login(userLoginVO);
		return R.okData(user);
	}
}

借鑒：
【1】SpringBoot從0到實戰(zhàn)8：簡單使用Swagger生成接口開發(fā)文檔
【2】 Swagger3 常用配置注解講解 結(jié)合SpringBoot2
【3】Swagger筆記—Swagger3詳細配置
【4】Swagger3的基本使用文章來源地址http://www.zghlxwxcb.cn/news/detail-720178.html

到了這里，關于swagger3的配置和使用（一）的文章就介紹完了。如果您還想了解更多內(nèi)容，請在右上角搜索TOY模板網(wǎng)以前的文章或繼續(xù)瀏覽下面的相關文章，希望大家以后多多支持TOY模板網(wǎng)！