SpringBoot專案中怎麼使用Swagger2及註解解釋

一、導入Swagger座標依賴

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>${swagger.version}</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>${swagger.version}</version>
</dependency>

其中版本最常用2.9.2

二、在spring啟動類別加入註解@ EnableSwagger2

springfox提供的@EnableSwagger2註解可以啟用swagger2相關技術。程式將遍歷目前類別所在的套件及其子套件中的所有類型，以尋找與Swagger相關的註解，並自訂Swagger文件

三、啟動項目，檢視swaggerui.html介面

#點擊try it out可以輸入對應的參數來查看回傳結果

四，編寫SwaggerConfig設定檔

@EnableSwagger2
@Configuration
public class SwaggerConfig {
    @Autowired
    private ApplicationContext applicationContext;

    private Contact contact = new Contact("NIUA","localhost:8080/swagger-ui.html", "1053288979@qq.com");

    @Bean
    public Docket createRestApi() {
        ServletContext servletContext = applicationContext.getBean(ServletContext.class);
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(Predicates.not(regex("/error.*")))
                .build()
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("平台接口 v1.0")
                .description("平台接口")
                .contact(contact)
                .version("1.0")
                .build();
    }
}

@Bean
    public Docket createRestApi() {
        ServletContext servletContext = applicationContext.getBean(ServletContext.class);
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(Predicates.not(regex("/error.*")))
                .build()
                .apiInfo(apiInfo());
    }

建立Docker類型的對象，並使用spring容器管理。 Docker是Swagger中的全域設定對象

使用DocumentationType.SWAGGER_2指定Docket的類別對象，以確定使用的是哪個版本

apiInfo()：API文件的描述訊息，參數是一個ApiInfo類別對象，使用bulid()建構器來建立

private ApiInfo apiInfo() {
       return new ApiInfoBuilder()
               .title("平台接口 v1.0")
               .description("平台接口")
               .contact(contact)
               .version("1.0")
               .build();
   }

contact()：配置swagger文件的主體內容，裡面填寫也是一個類別對象，類別物件最多可以三個參數，發佈者名稱，文件發佈者的網站url位址（企業網站），文件發佈者的電子郵件位址

private Contact contact = new Contact("NIUA","localhost:8080/swagger-ui.html", "1053288979@qq.com");

title()：標題description()：描述資訊.version()：版本資訊

對應以下內容

傳回ApiSelectorBuilder的方法是select()，用於取得Docker中的選擇器。建構選擇器。如掃描什麼包的註解

apis()：後面是RequestHandlerSelectors的類別下的(Predicate)規則，規定掃描那些包的註解，預設是啟動類別及其子包下的註解

RequestHandlerSelectors類別下有幾個靜態方法（舉例三個）

basePackage()：後面填入包名的具體位址，會掃描改包及其子包的註解

docker.apis(RequestHandlerSelectors.basePackage("com.xxx"))

any()：為任何介面產生API文檔

none()：任何介面都不產生介面文件

path()：使用正規表示式，約束生成Api文檔的路徑位址，後面填寫過濾（通過）的路徑

//过滤掉admin路径下的所有页面
.paths(Predicates.not(PathSelectors.regex("/admin/.*")))
//过滤掉所有error或error.*页面
.paths(Predicates.not(PathSelectors.regex("/error.*")))

//所有error或error.*页面或者admin路径下的所有页面都支持（or任意满足起一就通过）
.paths(Predicates.or(PathSelectors.regex("/error.*"),PathSelectors.regex("/admin/.*")))

五：Swagger支援自訂註解

這裡沒有提及，感興趣可以自己搜尋（留個位置，日後用到了補充）

六：Swagger2常用註解

#@Api(常用)

作用：@Api是類上註解。控制整個類別產生介面資訊的內容

屬性：

tags：類別的名稱。如果有多個值，這表示有多個副本（別名）可用，SwaggerUI視圖將顯示哪些控制器可透過哪些存取功能表

description：描述，已過時

@ApiOperation

#作用：@ApiOperation是方法上註解，描述方法的相關訊息

屬性：

value：方法描述作用

notes：方法筆記（展開描述）

@ApiParm

作用：@ApiParm是方法參數的註解。描述此參數

屬性：

name：參數名稱

value：描述參數作用

required：值為boolean類型，表示該參數是否為必要參數，預設為false

#

@ApiIgnore

作用：@ApiParm是方法或者参数的注解。忽略注解的方法或者参数，不生成帮助文档

@ApiImplicitParam(常用)

作用：@ApiParm是作用于类上方法，用来描述方法参数的注解。

属性：

name：参数名称，和方法的参数一致

value：参数具体描述

required：值为boolean类型，表示该参数是否为必要参数，默认为false

paramType：参数类型

paramType="字符串"
paramType = "header"

dataType：数据类型

dataType = "string"  //字符串数据
dataType = "键值对"

@ApiImplicitParams

后面跟@ApiImplicitParam的集合，一般用于多个参数的描述

@ApiImplicitParams({@ApiImplicitParam(name = "Authorization", value = "Authorization token", required = true, dataType = "string", paramType = "header")})

@ApiModel(常用)

作用：@ApiModel是作用于实体类上，描述一个实体类型，整个实体类型如果成为任何一个生成api帮助文档的返回对象的时候，该注解被解析

属性：

value：实体类名称

description：实体类描述

@ApiModelProperty(常用)

作用：@ApiModel是作用于实体类的属性上，描述实体类属性

属性：

value：实体属性描述

name：实体类属性名字，与属性名一致

以上是SpringBoot專案中怎麼使用Swagger2及註解解釋的詳細內容。更多資訊請關注PHP中文網其他相關文章！