一、導(dǎo)入Swagger坐標(biāo)依賴(lài)

<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啟動(dòng)類(lèi)添加注解@EnableSwagger2

@EnableSwagger2是springfox提供的一個(gè)注解，代表swagger2相關(guān)技術(shù)開(kāi)啟。會(huì)掃描當(dāng)前類(lèi)所在包，及子包中所有類(lèi)型的swagger相關(guān)注解，做swagger文檔的定制

三、啟動(dòng)項(xiàng)目，查看swaggerui.html界面

這是我開(kāi)發(fā)項(xiàng)目的地址，訪問(wèn)后可以看到swaggerui.html

http://localhost:9527/swagger-ui.html

點(diǎn)擊try it out可以輸入對(duì)應(yīng)的參數(shù)查看返回結(jié)果

四，編寫(xiě)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("平臺(tái)接口 v1.0")
                .description("平臺(tái)接口")
                .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());
    }

創(chuàng)建Docker類(lèi)型的對(duì)象，并使用spring容器管理。Docker是Swagger中的全局配置對(duì)象

DocumentationType.SWAGGER_2：給Docket一個(gè)類(lèi)對(duì)象，知道是那一個(gè)版本的

apiInfo()：API文檔的描述信息，參數(shù)是一個(gè)ApiInfo類(lèi)對(duì)象，使用bulid()構(gòu)建器來(lái)創(chuàng)建

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

contact()：配置swagger文檔的主體內(nèi)容，里面填寫(xiě)也是一個(gè)類(lèi)對(duì)象，類(lèi)對(duì)象最多可以三個(gè)參數(shù)，發(fā)布者名稱(chēng)，文檔發(fā)布者的網(wǎng)站url地址（企業(yè)網(wǎng)站），文檔發(fā)布者的電子郵箱地址

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

title()：標(biāo)題 description()：描述信息 .version()：版本信息

對(duì)應(yīng)如下內(nèi)容

select()：獲取Docker中的選擇器，返回ApiSelectorBuilder。構(gòu)建選擇器。如掃描什么包的注解

apis()：后面是RequestHandlerSelectors的類(lèi)下的(Predicate)規(guī)則，規(guī)定掃描那些包的注解，默認(rèn)是啟動(dòng)類(lèi)及其子包下的注解

RequestHandlerSelectors類(lèi)下有幾個(gè)靜態(tài)方法（舉例三個(gè)）

basePackage()：后面填寫(xiě)包名的具體地址，會(huì)掃描改包及其子包的注解

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

any()：為任何接口生成API文檔

none()：任何接口都不生成接口文檔

path()：使用正則表達(dá)式，約束生成Api文檔的路徑地址，后面填寫(xiě)過(guò)濾（通過(guò)）的路徑

//過(guò)濾掉admin路徑下的所有頁(yè)面
.paths(Predicates.not(PathSelectors.regex("/admin/.*")))
//過(guò)濾掉所有error或error.*頁(yè)面
.paths(Predicates.not(PathSelectors.regex("/error.*")))

//所有error或error.*頁(yè)面或者admin路徑下的所有頁(yè)面都支持（or任意滿(mǎn)足起一就通過(guò)）
.paths(Predicates.or(PathSelectors.regex("/error.*"),PathSelectors.regex("/admin/.*")))

五：Swagger支持自定義注解

這里沒(méi)有提及，感興趣可以自己搜索（留個(gè)位置，日后用到了補(bǔ)充）

六：Swagger2常用注解

@Api(常用)

作用：@Api是類(lèi)上注解?？刂普麄€(gè)類(lèi)生成接口信息的內(nèi)容

屬性：

tags：類(lèi)的名稱(chēng)。可以有多個(gè)值，多個(gè)值表示多個(gè)副本（別名），有幾個(gè)別名在swaggerui視圖上顯示幾個(gè)控制器訪問(wèn)菜單

description：描述，已過(guò)時(shí)

@ApiOperation

作用：@ApiOperation是方法上注解，描述方法的相關(guān)消息

屬性：

value：方法描述作用

notes：方法筆記（展開(kāi)描述）

@ApiParm

作用：@ApiParm是方法參數(shù)的注解。描述該參數(shù)

屬性：

name：參數(shù)名稱(chēng)

value：描述參數(shù)作用

required：值為boolean類(lèi)型，表示該參數(shù)是否為必要參數(shù)，默認(rèn)為false

@ApiIgnore

作用：@ApiParm是方法或者參數(shù)的注解。忽略注解的方法或者參數(shù)，不生成幫助文檔

@ApiImplicitParam(常用)

作用：@ApiParm是作用于類(lèi)上方法，用來(lái)描述方法參數(shù)的注解。

屬性：

name：參數(shù)名稱(chēng)，和方法的參數(shù)一致

value：參數(shù)具體描述

required：值為boolean類(lèi)型，表示該參數(shù)是否為必要參數(shù)，默認(rèn)為false

paramType：參數(shù)類(lèi)型

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

dataType：數(shù)據(jù)類(lèi)型

dataType = "string"  //字符串?dāng)?shù)據(jù)
dataType = "鍵值對(duì)" 

@ApiImplicitParams

后面跟@ApiImplicitParam的集合，一般用于多個(gè)參數(shù)的描述

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

@ApiModel(常用)

作用：@ApiModel是作用于實(shí)體類(lèi)上，描述一個(gè)實(shí)體類(lèi)型，整個(gè)實(shí)體類(lèi)型如果成為任何一個(gè)生成api幫助文檔的返回對(duì)象的時(shí)候，該注解被解析

屬性：

value：實(shí)體類(lèi)名稱(chēng)

description：實(shí)體類(lèi)描述

@ApiModelProperty(常用)

作用：@ApiModel是作用于實(shí)體類(lèi)的屬性上，描述實(shí)體類(lèi)屬性

屬性：

value：實(shí)體屬性描述

name：實(shí)體類(lèi)屬性名字，與屬性名一致

總結(jié)

到此這篇關(guān)于SpringBoot項(xiàng)目中使用Swagger2及注解解釋的文章就介紹到這了,更多相關(guān)SpringBoot使用Swagger2內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

最新評(píng)論