springBoot項目整合Swagger2

swagger版本號：2.9.2

swagger是什麼

官方說法：Swagger是一個規範和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。總體目標是使客戶端和文件系統作爲服務器以同樣的速度來更新。文件的方法，參數和模型緊密集成到服務器端的代碼，允許API來始終保持同步

目前小鹹兒做的項目是前後端分離的，爲了更好的進行調試，所以後端需要提供一個API接口文檔，這樣開發起來更加的方便快捷。

springBoot和swagger進行整合

第一步：在pom.xml文件中引入jar包

<dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>2.9.2</version>
 </dependency>

 <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger-ui</artifactId>
      <version>2.9.2</version>
 </dependency>
 <dependency>
      <groupId>io.swagger</groupId>
      <artifactId>swagger-annotations</artifactId>
      <version>1.5.19</version>
  </dependency>

第二步：配置swagger

新建一個配置文件swagger2，可以放在和controller包同等級的配置包中。

package com.miaoshaproject.config;

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;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * swagger的配置信息
 * @author Phyllis
 * @date 2019年7月25日09:23:13
 */
@Configuration
@EnableSwagger2
public class Swagger2 {


    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.miaoshaproject.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("miaosha APIs")
                .description("")
                .termsOfServiceUrl("")
                .version("1.0")
                .build();
    }

}

註解

接下來就該在controller層中寫入註解

首先需要在類上加入@RestController註解，這裏的@RestController和@Controller可是不同的，@RestController=@Controller+@ResponseBody
還需要添加上@Api(tags = {“用戶信息接口”})

接着就可以在方法上添加註解了

@ApiOperation() 用於方法；表示一個http請求的操作
value用於方法描述 notes用於提示內容 tags可以重新分組（視情況而用）

示例：

@ApiOperation(value = "用戶註冊",notes = "根據用戶信息進行用戶註冊")

在方法中的參數上添加註解

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

示例：

 public User getUserInfo(@ApiParam(name="id",value="用戶id",required=true) Long id,@ApiParam(name="username",value="用戶名") String username) {
         //業務邏輯忽略
}

項目啓動

問題

一開始小鹹兒整合的時候，只要Swagger的版本高於2.7.0以上，再啓動項目後就不顯示swagger頁面，只顯示如上圖所示，但是也不報錯，經過種種的排錯以及嘗試各種解決方法之後，最終發現有兩個原因：

1、是沒有導入swagger-annotations jar包
2、是在controller層使用的是@Controller，一開始沒懂@RestController和@Controller的區別，後來明白@RestController=@Controller+@ResponseBody

至於爲什麼小鹹兒沒有將就使用2.7.0版本的，一個是因爲那個版本的swagger頁面實在是不好看，二是不將就是發現問題的原動力，果然發現問題就解決問題了。

springBoot項目整合Swagger2