SpringBoot第十五篇：swagger構建優雅文檔

做者：追夢1819
原文：https://www.cnblogs.com/yanfei1819/p/11007470.html
版權聲明：本文爲博主原創文章，轉載請附上博文連接！

引言

  前面的十四篇文介紹了 SpringBoot 的一些基本和經常使用的功能。後面，咱們將介紹 SpringBoot 的高級的功能、框架原理以及使用技巧。

  一個項目組可能由前端、後端、安卓、IOS等衆多的開發人員或者衆多開發團隊組成。內部的 API 共同成本巨大。主要體如今幾個方面：

• 接口多且複雜；
• 細節之處繁雜：通信協議、參數、返回值、接口說明、路徑等；
• 接口的維護。功能接口是隨着時間迭代升級的，所以這增長了接口文檔的管理成本。

  所以，團隊內部的溝通，一直都是開發人員的一個痛點。而手動編寫 api 文檔，不只效率低，並且容易遺漏、不能及時同步更新。swagger 框架很好的解決了此問題。

swagger簡介

  swagger 優雅的解決了這個問題。它是一個功能強大的API框架，它的集成很是簡單，不只提供了在線文檔的查閱，並且還提供了在線文檔的測試。swagger 是一個規範和完整的框架，用於生成、描述、調用和可視化 RESTful 風格的 Web 服務。整體目標是使客戶端和文件系統做爲服務器以一樣的速度來更新。文件的方法，參數和模型緊密集成到服務器端的代碼，容許API來始終保持同步。swagger 讓部署管理和使用功能強大的 API 從未如此簡單。

版本信息

• JDK：1.8
• SpringBoot ：2.1.4.RELEASE
• maven：3.3.9
• swagger2：2.4.0
• swagger-bootstrap-ui：1.7
• IDEA：2019.1.1

swagger 經常使用註解

  swagger 經過註解代表該接口會生成文檔，包括接口名、請求方法、參數、返回信息的等等。

• @Api：修飾整個類，描述Controller的做用

• @ApiOperation：描述一個類的一個方法，或者說一個接口

• @ApiParam：單個參數描述

• @ApiModel：用對象來接收參數

• @ApiProperty：用對象接收參數時，描述對象的一個字段

• @ApiResponse：HTTP響應其中1個描述

• @ApiResponses：HTTP響應總體描述

• @ApiIgnore：使用該註解忽略這個API

• @ApiError ：發生錯誤返回的信息

• @ApiImplicitParam 一個參數

• @ApiImplicitParams 多個參數

  
  

swagger使用

  爲了更加形象說明 swagger 的使用，下面建立一個實例項目以做演示。

首先，引入 maven 依賴：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

<!-- swagger用於定義API文檔 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.4.0</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.4.0</version>
</dependency>

而後，配置 swagger：

package com.yanfei1819.swaggerdemo;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
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 Swagger2 {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.yanfei1819.swaggerdemo.controller"))
//                .paths(AppUtility.isProd() ? PathSelectors.none() : PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("測試swagger")
                .description("展現swagger界面")
                .termsOfServiceUrl("http://localhost:8084/swagger-ui.html")
                .contact(new Contact("追夢1819", "http://localhost:8084/swagger-ui.html", "xxx@163.com"))
                .version("1.0")
                .build();
    }
}

下一步，建立幾個測試方法：

package com.yanfei1819.swaggerdemo.controller;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import springfox.documentation.annotations.ApiIgnore;

/**
 * Created by 追夢1819 on 2019-05-06.
 */
@Controller
@RequestMapping("/swagger-a")
@Api(value = "測試第一個controller")
public class SwaggerAController {
    @ApiOperation(value = "controllerA的測試方法一",notes = "controllerA的測試方法一")
    @GetMapping("/test1")
    public void test1(){}

    @ApiOperation(value = "controllerA的測試方法二",notes = "controllerA的測試方法二")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "name", value = "用戶姓名", required = true, dataType = "String"),
            @ApiImplicitParam(name = "password", value = "用戶密碼", required = true, dataType = "String")
    })
    @PostMapping("/test2")
    public void test2(String name,String password){}

    @ApiOperation(value = "controllerA的測試方法三",notes = "controllerA的測試方法三")
    @ApiImplicitParam(name = "name", value = "用戶姓名", required = true, dataType = "String")
    @GetMapping("/test3")
    public void test3(String name){}

    // 該接口忽略
    @ApiIgnore
    @GetMapping("/test4")
    public void test4(String name){}
}

最後，訪問：http://localhost:8084/swagger-ui.htm，生成的相應的界面：

優化swagger界面

  swagger 原生的界面談不上美觀。swagger-bootstrap-ui是springfox-swagger的加強UI實現，爲Java開發者在使用 swagger 的時候，能擁有一份簡潔、強大的接口文檔體驗。

  swagger-bootstrap-ui提供兩大核心功能：文檔說明 和 在線調試，如下做說明。

在以上實例的基礎上，引入maven依賴便可：

<!--美化swagger-->
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>swagger-bootstrap-ui</artifactId>
    <version>1.7</version>
</dependency>

而後，訪問 http://localhost:8084/doc.html，看看效果：

總結

  其實對於做者來講，我並不喜歡這種這種編碼風格。雖然生成了 spi 文檔，可是其註解對接口的污染較大。算是事有利弊吧，主要衡量利弊輕重。

  源碼：個人GitHub