SpringBoot 實戰 | 集成 Swagger2

什麼是Swagger2

      Swagger 是一個規範和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。

Swagger的優點  

      1、文檔自動更新

      2、可以直接測試文檔

      3、易於管理，一次配置即可使用

      4、接口返回結果明確，包括數據類型、狀態碼、錯誤信息。

集成步驟

       首先創建一個SpringBoot工程（開發工具idea，也可在spring官網生成工程）

 

 然後Next,finish。

 一、SpringBoot生成後，在Pom文件添加如下依賴：

        <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>

二、在SpringBoot啓動類（Application）添加Swagger註解並且在同級目錄新建一個Swagger配置類（Swagger2配置類必須與Application位於同一級目錄，負責生成Api文檔失敗），代碼如下：

 

 

package com.swagger.swagger;

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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Swagger2Config {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                //文檔信息對象
                .apiInfo(apiInfo())
                .select()
                //被註解的包路徑
                .apis(RequestHandlerSelectors.basePackage("com.swagger.swagger"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo(){
        return new ApiInfoBuilder()
                //標題
                .title("Springboot 利用 swagger 構建 API 文檔")
                //Api文檔描述
                .description("SpringBoot集成Swagger")
                .termsOfServiceUrl("https://www.baidu.com")
                //文檔作者信息
                .contact(new Contact("亖石磊","www.sishilei.com","[email protected]"))
                .version("1.0")
                //文檔版本
                .build();
    }
}

三、編寫被註解的Controller類以及各個接口請求參數，返回結果，接口描述等，代碼如下：

package com.swagger.swagger.controller;

import com.swagger.swagger.model.Car;
import com.swagger.swagger.service.CarService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@RequestMapping("/car")
@Api("Car Api接口文檔")
public class CarController {
    @Autowired
    private CarService carService;

    @ApiOperation(value = "獲取所有車輛列表",notes="獲取所有車輛列表")
    @GetMapping("/list")
    public List<Car> listCar(){
        List<Car> carList = carService.listCar();
        return carList;
    }

    @PostMapping("/save")
    @ApiOperation(value = "添加車輛信息",notes="添加車輛信息")
    @ApiImplicitParam(name="car",value = "車輛實體類",required = true,dataType = "Car")
    public Car save(@RequestBody Car car){
        return carService.save(car);
    }
}

package com.swagger.swagger.model;

public class Car {
}

package com.swagger.swagger.service;

import com.swagger.swagger.model.Car;
import org.springframework.stereotype.Service;

import java.util.ArrayList;
import java.util.List;

@Service
public class CarService {
    public Car save(Car car) {
        return new Car();
    }

    public List<Car> listCar() {
        return new ArrayList<>();
    }
}

四、啓動項目，訪問http://localhost:8080/swagger-ui.html，結果圖如下：

 Swagger2 常用註解簡介

 

@ApiOperation：用在方法上，說明方法的作用
  1.value: 表示接口名稱
  2.notes: 表示接口詳細描述 
@ApiImplicitParams：用在方法上包含一組參數說明
@ApiImplicitParam：用在@ApiImplicitParams註解中，指定一個請求參數的各個方面
  1.paramType：參數位置
  2.header 對應註解：@RequestHeader
  3.query 對應註解：@RequestParam
  4.path  對應註解: @PathVariable
  5.body 對應註解: @RequestBody
  6.name：參數名
  7.dataType：參數類型
  8.required：參數是否必須傳
  9.value：參數的描述
  10.defaultValue：參數的默認值
@ApiResponses：用於表示一組響應
@ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應信息
  1.code：狀態碼
  2.message：返回自定義信息
  3.response：拋出異常的類
@ApiIgnore: 表示該接口函數不對swagger2開放展示
@Api：修飾整個類，描述Controller的作用
@ApiParam：單個參數描述
@ApiModel：用對象來接收參數
@ApiProperty：用對象接收參數時，描述對象的一個字段
@ApiIgnore：使用該註解忽略這個API
@ApiError ：發生錯誤返回的信息

注意事項

@ApiImplicitParam 註解下的 paramType 屬性,會影響接口的測試,如果設置的屬性跟spring 的註解對應不上,會獲取不到參數,例如 paramType=path ,函數內卻使用@RequestParam 註解,這樣,可能會獲取不到傳遞進來的參數,需要按照上面進行對應,將 @RequestParam 註解改爲 @PathVariable 才能獲取到對應的參數。