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

<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

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

三、啟動項目，查看swaggerui.html界面

這是我開發(fā)項目的地址，訪問后可以看到swaggerui.html

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

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

四，編寫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());
    }

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

DocumentationType.SWAGGER_2：給Docket一個類對象，知道是那一個版本的

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

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

contact()：配置swagger文檔的主體內(nèi)容，里面填寫也是一個類對象，類對象最多可以三個參數(shù)，發(fā)布者名稱，文檔發(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()：版本信息

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

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

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

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

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是類上注解?？刂普麄€類生成接口信息的內(nèi)容

屬性：

tags：類的名稱?？梢杂卸鄠€值，多個值表示多個副本（別名），有幾個別名在swaggerui視圖上顯示幾個控制器訪問菜單

description：描述，已過時

@ApiOperation

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

屬性：

value：方法描述作用

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

@ApiParm

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

屬性：

name：參數(shù)名稱

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

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

@ApiIgnore

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

@ApiImplicitParam(常用)

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

屬性：

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

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

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

paramType：參數(shù)類型

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

dataType：數(shù)據(jù)類型

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

@ApiImplicitParams

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

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

@ApiModel(常用)

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

屬性：

value：實體類名稱

description：實體類描述

@ApiModelProperty(常用)

作用：@ApiModel是作用于實體類的屬性上，描述實體類屬性

屬性：

value：實體屬性描述

name：實體類屬性名字，與屬性名一致

總結(jié)

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

最新評論