堅(jiān)持學(xué)習(xí)第五天：SpringBoot 2.x 整合Swagger2 生成接口文檔

認(rèn)真是一種態(tài)度,堅(jiān)持是一種品格,優(yōu)秀是一種習(xí)慣窖维！
????隨著技術(shù)的不斷革新啦吧，目前大多數(shù)互聯(lián)網(wǎng)公司引進(jìn)了前后端分離的開發(fā)模式颜武。前端負(fù)責(zé)頁面的開發(fā)璃搜，包括頁面樣式以及相關(guān)接口對接；而后端則專注于后臺業(yè)務(wù)的實(shí)現(xiàn)鳞上。這樣確實(shí)極大的提高了開發(fā)效率这吻。但同時也帶了溝通上的問題，因?yàn)榻涌诙际呛笈_實(shí)現(xiàn)和提供的因块。那么就必須寫好相應(yīng)的接口文檔橘原，告知前端接口地址、接口參數(shù)規(guī)范等等涡上。因此我們引入了swagger一個為接口文檔而生的開源項(xiàng)目趾断，它以注解的方式，讓后端在開發(fā)過程中就可以通過簡單便捷的方式完成接口文檔編寫吩愧。
效果如下圖：

接口文檔效果

基礎(chǔ)理論

swagger常用注解及說明：
@Api():用于類芋酌，標(biāo)識這個類是swagger的資源
@ApiOperation():用于方法,表示一個http請求的操作
@ApiParam():用于方法，參數(shù)雁佳，字段說明脐帝；表示對參數(shù)的添加元數(shù)據(jù)（說明或是否必填等）
@ApiModel():用于類 ,表示對類進(jìn)行說明同云，用于參數(shù)用實(shí)體類接收
@ApiModelProperty():用于方法，字段 ,表示對model屬性的說明或者數(shù)據(jù)操作更改
@ApiIgnore():用于類堵腹，方法炸站，方法參數(shù) ,表示這個方法或者類被忽略
@ApiImplicitParam(): 用于方法 ,表示單獨(dú)的請求參數(shù)
@ApiImplicitParams(): 用于方法，包含多個@ApiImplicitParam
Tips:
若參數(shù)實(shí)體類某個參數(shù)不想顯示到接口文檔中疚顷，可通過ApiModelProperty實(shí)現(xiàn)旱易，實(shí)現(xiàn)方式：
@ApiModelProperty(hidden=true)

那么我們現(xiàn)在就簡單說說Springboot項(xiàng)目中如何整合進(jìn)swagger2.

項(xiàng)目框架：

JDK 1.8
SpringBoot 2.1.5.RELEASE
Swagger 2.9.2
swagger-bootstrap-ui 1.9.4

創(chuàng)建項(xiàng)目

在堅(jiān)持學(xué)習(xí)第一天中已經(jīng)講過SpringBoot項(xiàng)目的創(chuàng)建了，此處不再贅述腿堤》Щ担可直接參考。

整合swagger2

Maven依賴添加
在項(xiàng)目pom.xml中添加swagger2相應(yīng)的依賴笆檀。

      <!-- swagger2 主要依賴 --->
      <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
       <!-- swagger2 默認(rèn)主題樣式 --->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
       <!-- swagger2 bootstrap風(fēng)格主題樣式 --->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.4</version>
        </dependency>

swagger配置
在項(xiàng)目中添加swagger基礎(chǔ)配置(SwaggerConfig.java)

package com.cooper.common;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

/**
 * Swagger配置
 */
@Configuration
public class SwaggerConfig {

    /**
     * 通過 createRestApi函數(shù)來構(gòu)建一個DocketBean
     * 函數(shù)名,可以隨意命名,喜歡什么命名就什么命名
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .enable(true)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.cooper.module"))
                .paths(PathSelectors.any())
                .build()
                .useDefaultResponseMessages(false)
                .apiInfo(apiInfo());
    }


    /**
     * 構(gòu)建 api文檔的詳細(xì)信息函數(shù)
     * @return  ApiInfo
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("copper_sp 接口文檔")
                .version("v1.0.0")
                .description("copper_sp 接口文檔")
                .build();
    }

}

啟動類中指定啟用Swagger
在項(xiàng)目啟動主類添加注解@EnableSwagger2指定啟用swagger.

package com.cooper;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@EnableSwagger2
@SpringBootApplication
public class CooperSpApplication {

    public static void main(String[] args) {
        SpringApplication.run(CooperSpApplication.class, args);
    }

}

此時我們啟動項(xiàng)目忌堂，訪問默認(rèn)接口地址：xxxx/swagger-ui.html效果如下：

默認(rèn)swagger接口文檔

然后我們在訪問一下bootstrap風(fēng)格的接口地址：
xxxx/doc.html效果如下：

bootstrap風(fēng)格接口文檔

至此基本的整合我們就完成了。當(dāng)然部分整合時可能會出現(xiàn)swagger-ui.html和doc.html訪問地址報(bào)404.若出現(xiàn)此等問題酗洒，可以嘗試將這兩個路由添加到springboot的資源管理中士修，實(shí)現(xiàn)方式如下：通過實(shí)現(xiàn)WebMvcConfigurer類后重寫addResourceHandlers方式實(shí)現(xiàn)：


public class WebConfig  implements  WebMvcConfigurer { 

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/");
        registry.addResourceHandler("swagger-ui.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("doc.html")
                .addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
                .addResourceLocations("classpath:/META-INF/resources/webjars/"); 
    }
}

寫個接口文檔試試

上面我們已經(jīng)將swagger整合到springboot中了，接下來我們就寫個接口文檔看看效果寝蹈。

接口文檔

 @ApiOperation(value = "分頁獲取用戶信息")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name",value = "名稱",dataType = "String"),
            @ApiImplicitParam(name = "current",value = "當(dāng)前頁",required = true,dataType = "int",example = "1"),
            @ApiImplicitParam(name = "size",value = "分頁條數(shù)",required = true,dataType = "int",example = "10"),
    })
    @RequestMapping(value = "/list-with-page",method = {RequestMethod.GET,RequestMethod.POST})
    @ResponseBody
    public IPage<User> listWithPage(String name, Page<User> page){
        return userService.listWithPage(name,page);
    }

實(shí)際生成效果

image.png

image.png

至此springboot整合swagger2基本算完成了李命。我們可以稍許簡單的方式編寫接口文檔了。更多swagger知識箫老，待下次補(bǔ)充封字。
若有哪位好友有更方便快捷的方式歡迎賜教。