springboot中swagger的應用總結

背景：

           近年，公司項目基本上都是採用的前後端分離的方式。前後端的聯繫，除了開發人員的直接溝通，更需要一個可靠、高效的API文檔，經過探索，選擇了使用swagger。特此總結一下用法，遇到的問題，用紅色標註出來。

---

目錄

背景：

1、swagger簡介

2、依賴引入

3、基本配置

4、常用註解

5、例子

---

---

1、swagger簡介

        Swagger：根據後臺代碼註解可以在線自動生成接口文檔，並允許API始終與代碼保持同步。

        springboot整合爲例，啓動服務後，訪問http://ip:port/swagger-ui.html，就可以在線訪問接口文檔了，

        還可以直接在在線文檔中進行接口測試。

        Swagger是一組開源項目，其中主要要項目如下：

        1.   Swagger-tools:提供各種與Swagger進行集成和交互的工具。例如模式檢驗、Swagger 1.2文檔轉換成Swagger 2.0文檔等功能。

        2.   Swagger-core: 用於Java/Scala的的Swagger實現。與JAX-RS(Jersey、Resteasy、CXF...)、Servlets和Play框架進行集成。

        3.   Swagger-js: 用於JavaScript的Swagger實現。

        4.   Swagger-node-express: Swagger模塊，用於node.js的Express web應用框架。

        5.   Swagger-ui：一個無依賴的HTML、JS和CSS集合，可以爲Swagger兼容API動態生成優雅文檔。

        6.   Swagger-codegen：一個模板驅動引擎，通過分析用戶Swagger資源聲明以各種語言生成客戶端代碼。

2、依賴引入

       需要引入兩個依賴

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

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.7.0</version>
</dependency>

3、基本配置

        需要用到兩個方法，

         一個是配置掃描路徑，掃描該包路徑下所有@Controller或者@RestController的類；再根據具體的API註解生成文檔，注意，只有帶 @**Mapping 註解的方法纔會生成接口文檔，且即使沒有@ApiOperation、@ApiImplicitParams也會根據方法名生成。當然，我們使用這兩個註解，生成的文檔纔會有詳細的說明。

        另一個方法則是配置文檔首頁的一些展示內容；

package com.cqndt.mytest.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(用於生成、描述、調用和可視化RESTful風格的Web服務)配置類
 * 訪問地址：http://localhost:8080/swagger-ui.html
 * @author
 */

@EnableSwagger2
@Configuration
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                //apis()指定掃描的包會生成文檔
                .apis(RequestHandlerSelectors.basePackage("com.cqndt.mytest"))
                .paths(PathSelectors.any())
                .build();
    }
    /**
     * 構建 api文檔的詳細信息函數
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //頁面標題
                .title("測試項目")
                //描述
                .description("公司官網，http://www.cqndt.com")
                .termsOfServiceUrl("http://www.cqndt.com")
                //版本號
                .version("1.0")
                .build();
    }
}

4、常用註解

• @Api：用在類上，說明該類的作用

  @Api(value = "ceshi", description = "用於測試分頁")

• @ApiOperation：用在方法上，說明方法的作用

  @ApiOperation(value = "用戶表分頁獲取接口（get方法，restful傳參）", notes = "用於測試分頁插件")

• @ApiImplicitParams：用在方法上包含一組參數說明
• @ApiImplicitParam：用在@ApiImplicitParams註解中(如果只有一個參數，也可以單獨用這個註解)，指定一個請求參數的各個方面
  • paramType：參數放在哪個地方（參數的獲取方式和paramType類型要一致，否則測試會出現獲取不到參數的情況）
    • header-->請求參數的獲取：@RequestHeader
    • query-->請求參數的獲取：@RequestParam 
    • path（用於restful接口）-->請求參數的獲取：@PathVariable   
    • body（不常用）
    • form（不常用）
  • name：參數名
  • dataType：參數類型
  • required：參數是否必須傳
  • value：參數的意思
  • defaultValue：參數的默認值
• @ApiResponses：用於表示一組響應
• @ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應信息
  • code：數字，例如400
  • message：信息，例如"請求參數沒填好"
  • response：拋出異常的類
• @ApiModel：描述一個Model的信息（這種一般用在post創建的時候，使用@RequestBody這樣的場景，請求參數無法使用@ApiImplicitParam註解進行描述的時候）
  • @ApiModelProperty：描述一個model的屬性

5、例子

        下面測試類裏面包含了4個方法：

        getUsers1() : restful接口，get請求，從路徑中獲取參數，paramType配置爲path;

        getUsers2() : post請求，從表單中獲取參數，paramType = "query"；

        getUsers3() ：沒有規定請求類型，可以看到生成了7個API，也就是swagger對於這種沒有明確規定的類型，認爲都可以。

        getUsers4() ：沒有mapping，swagger不會給其生成api文檔；

package com.cqndt.mytest.controller;

import com.cqndt.mytest.service.UserService;
import com.cqndt.mytest.utils.Result;
import com.github.pagehelper.PageHelper;
import com.github.pagehelper.PageInfo;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.web.bind.annotation.*;

import java.util.List;
import java.util.Map;

/**
 * Created By alun
 * Date: 2018/12/3
 * Time: 15:17
 * Description:
 */
@RestController
@RequestMapping("test")
@Api(value = "ceshi", description = "用於測試分頁")
public class HelloController {

    private static final Logger LOGGER = LoggerFactory.getLogger(HelloController.class);

    @Autowired
    private UserService userService;

    @GetMapping("users/{id}/{page}/{rows}")
    @ApiOperation(value = "用戶表分頁獲取接口（get方法，restful傳參）", notes = "用於測試分頁插件")
    @ApiImplicitParams({
            @ApiImplicitParam(dataType = "int", name = "id", value = "id號", defaultValue = "1", required = false, paramType = "path"),
            @ApiImplicitParam(dataType = "int", name = "page", value = "開始頁數", defaultValue = "1", required = false, paramType = "path"),
            @ApiImplicitParam(dataType = "int", name = "rows", value = "頁條數", defaultValue = "10", required = false, paramType = "path")
    })
    private Result getUsers1(@PathVariable int id,@PathVariable int page,@PathVariable int rows){

        LOGGER.info("id:"+id+" , page:"+page+" , rows:"+rows);
        PageHelper.startPage(page, rows);
        List<Map<String,Object>> list = userService.getUsers();
        System.out.println(list);
        PageInfo<Map<String, Object>> pageInfo = new PageInfo<Map<String, Object>>(list);
        return new Result().success(pageInfo);
    }

    @PostMapping("users")
    @ApiOperation(value = "用戶表分頁獲取接口（post方式）", notes = "用於測試分頁插件")
    @ApiImplicitParams({
            @ApiImplicitParam(dataType = "int", name = "id", value = "id號", defaultValue = "1", required = false, paramType = "query"),
            @ApiImplicitParam(dataType = "int", name = "page", value = "開始頁數", defaultValue = "1", required = false, paramType = "query"),
            @ApiImplicitParam(dataType = "int", name = "rows", value = "頁條數", defaultValue = "10", required = false, paramType = "query")
    })
    private Result getUsers2(int id,int page,int rows){

        LOGGER.info("id:"+id+" , page:"+page+" , rows:"+rows);
        PageHelper.startPage(page, rows);
        List<Map<String,Object>> list = userService.getUsers();
        System.out.println(list);
        PageInfo<Map<String, Object>> pageInfo = new PageInfo<Map<String, Object>>(list);
        return new Result().success(pageInfo);
    }

    @RequestMapping("users3")
    private Result getUsers3(int id,int page,int rows){

        LOGGER.info("id:"+id+" , page:"+page+" , rows:"+rows);
        PageHelper.startPage(page, rows);
        List<Map<String,Object>> list = userService.getUsers();
        System.out.println(list);
        PageInfo<Map<String, Object>> pageInfo = new PageInfo<Map<String, Object>>(list);
        return new Result().success(pageInfo);
    }

    private Result getUsers4(int id,int page,int rows){

        LOGGER.info("id:"+id+" , page:"+page+" , rows:"+rows);
        PageHelper.startPage(page, rows);
        List<Map<String,Object>> list = userService.getUsers();
        System.out.println(list);
        PageInfo<Map<String, Object>> pageInfo = new PageInfo<Map<String, Object>>(list);
        return new Result().success(pageInfo);
    }
}

 

以下是生成的文檔，

參考文章：

Spring Swagger URL傳參問題（轉）

Swagger使用指南