Springboot2.x整合Swagger3.x

1、SpringBoot添加pom文件依賴

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.4.11</version>
        <relativePath/>
    </parent>

    <properties>
        <java.version>11</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <!--swagger3依賴-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-boot-starter</artifactId>
            <version>3.0.0</version>
        </dependency>

        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <version>1.18.16</version>
            <scope>provided</scope>
        </dependency>

    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

 

2、配置文件增加配置

server:
  port: 8082

spring:
  application:
    name: swagger-server

swagger:
  enable: true
  application-name: ${spring.application.name}
  application-version: 1.0
  application-description: 電商平台管理后端接口文檔

 

3、創建配置類

import io.swagger.annotations.ApiOperation;
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Component;
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.Collections;
import java.util.List;

/**
 * @author baot
 * @title Swagger3 插件配置
 * @description
 * @date 2021-10-14
 * @update
 * @className SwaggerConfiguration
 */
@Component
@EnableOpenApi
@ConfigurationProperties("swagger")
@Data
public class SwaggerConfiguration {
    /**
     * 是否開啟swagger，生產環境一般關閉，所以這里定義一個變量
     */
    private Boolean enable;

    /**
     * 項目應用名
     */
    private String applicationName;

    /**
     * 項目版本信息
     */
    private String applicationVersion;

    /**
     * 項目描述信息
     */
    private String applicationDescription;

    @Bean
    public Docket docket() {
        return new Docket(DocumentationType.OAS_30)
                .pathMapping("/")
                // 定義是否開啟swagger，false為關閉，可以通過變量控制，線上關閉
                .enable(enable)
                .select()
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any()).build()
                // 如何保護我們的Api，有三種驗證（ApiKey, BasicAuth, OAuth）
                .securitySchemes(security())
                //全局控制token
                .securityContexts(Collections.singletonList(SecurityContext.builder().securityReferences(Collections.singletonList(SecurityReference.builder().scopes(new AuthorizationScope[0]).reference("token").build()))
                 // 聲明作用域
                 .operationSelector(o -> o.requestMappingPattern().matches("/.*"))
                 .build()))
                // 接口文檔的基本信息
                .apiInfo(apiInfo());
    }


    /**
     * 接口文檔詳細信息
     *
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title(applicationName)
                .description(applicationDescription)
                //.contact(new Contact("聯系標題", "https://www.baidu.com", "[e-mail]"))
                .version(applicationVersion)
                .build();
    }

    private List<SecurityScheme> security() {
        ArrayList<SecurityScheme> apiKeys = new ArrayList<>();
        apiKeys.add(new ApiKey("token", "token", "header"));
        return apiKeys;
    }
    
}

 

4、創建controller類

import com.example.model.User;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import org.springframework.web.bind.annotation.*;

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

@Api(tags = "測試接口")
@RestController
@RequestMapping("demo")
public class DemoController {

    @ApiOperation("查詢集合數據")
    @ApiImplicitParams(value = {
            @ApiImplicitParam(name = "id",value = "查詢id"),
            @ApiImplicitParam(name = "name",value = "查詢名稱",required = true)
    })
    @ApiResponses({
            @ApiResponse(responseCode = "200", description ="OK"),
            @ApiResponse(responseCode = "204", description ="No results returned")
    })
    @PostMapping("list1")
    public List<String> list1(Integer id,String name){
        List<String> list = new ArrayList<>();
        list.add("張三");
        list.add("李四");
        return list;
    }

    @ApiOperation("測試刪除")
    @ApiImplicitParam(name = "id", value = "刪除ID", example = "100", required = true)
    @PostMapping(value = "/delete/{id}")
    public Integer delete(@PathVariable("id") Long id){
        System.out.println("刪除成功："+id);
        return 200;
    }

    @ApiOperation("保持對象")
    @PostMapping("save")
    public Object save(@RequestBody User user){
        User user1 = new User();
        user1.setId(user.getId());
        user1.setName(user.getName());
        return user1;
    }

}

 

5、訪問 http://localhost:8082/swagger-ui/index.html

 

6、常用注解，官網

- @Api()用於類；
表示標識這個類是swagger的資源

- @ApiOperation()用於方法；
表示一個http請求的操作

- @ApiParam()用於方法，參數，字段說明；
表示對參數的添加元數據（說明或是否必填等）

- @ApiModel()用於類
表示對類進行說明，用於參數用實體類接收

- @ApiModelProperty()用於方法，字段
表示對model屬性的說明或者數據操作更改

- @ApiIgnore()用於類，方法，方法參數
表示這個方法或者類被忽略

- @ApiImplicitParam() 用於方法
表示單獨的請求參數

- @ApiImplicitParams() 用於方法，包含多個 @ApiImplicitParam

具體使用舉例說明：

@Api()
用於類；表示標識這個類是swagger的資源
tags–表示說明
value–也是說明，可以使用tags替代