從零開始SpringCloud Alibaba電商系統(八)——用一個好看的Swagger接口文檔

Befor All：按照本來計劃，這一次應該繼續spring security，來做SSO的部分，但是想到我們之前都是url訪問各個接口實在過於不便且ugly，故本次我們集成swagger、swagger-bootstrap-ui做一個界面好看點兒的api接口文檔及接口測試工具。

零、系列

歡迎來嫖從零開始SpringCloud Alibaba電商系列:

1. 從零開始SpringCloud Alibaba電商系統(一)——Alibaba與Nacos服務註冊與發現
2. 從零開始SpringCloud Alibaba電商系統(二)——Nacos配置中心
3. 從零開始SpringCloud Alibaba電商系統(三)——Sentinel流量防衛兵介紹、流量控制demo
4. 從零開始SpringCloud Alibaba電商系統(四)——Sentinel的fallback和blockHandler
5. 從零開始SpringCloud Alibaba電商系統(五)——Feign Demo，Sentinel+Feign實現多節點間熔斷/服務降級
6. 從零開始SpringCloud Alibaba電商系統(六)——Sentinel規則持久化到Nacos配置中心
7. 從零開始SpringCloud Alibaba電商系統(七)——Spring Security實現登錄認證、權限控制

二、Swagger是什麼？

誠如一開始所說，swagger是一個接口文檔，它可以將我們的所有Controller和它們的方法列在頁面上，讓我們可以不必自己再手寫接口文檔，當然Swagger也可以讓我們爲Controller方法們加上描述，讓方法的含義展示更清晰。

swagger還可以部分代替postman，我們可以直接在swagger提供的界面上像使用postman一樣對本項目的接口發送請求。

來一個例圖：

這是swagger自帶的ui界面，有點兒ugly，稍後我們在實操中換成一套較爲好看的swagger-bootstrap-ui頁面。

三、Springboo集成Swagger

1. 在上次demo引入maven依賴，使用demo請配置可用的nacos和sentinel dashboard或屏蔽掉。

 <!--Swagger-UI API文檔生產工具-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>
        
        <!-- 一個好看的swagger-ui界面-->
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.8.1</version>
        </dependency>

2. 使用spring的Java Config配置Swagger相關配置，主要是兩方面：Swagger基本配置、頁面樣式配置。

package com.lele.mall.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
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;

@Configuration
@EnableSwagger2
public class Swagger2Config implements WebMvcConfigurer {
    @Bean
    public Docket createRestApi(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.lele.mall.controller")) // 爲controller生成文檔
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("電商系統文檔")
                .version("1.0")
                .build();
    }

    // 頁面樣式替換爲swagger-bootstrap-ui
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

3. Controller都增加@Api註解並增加tags屬性用於描述。

@Api(tags = "訂單服務")
@RequestMapping("/order")
@RestController
public class OrderController {

4. 爲/test，/order/apply等接口方法增加ApiOperation並增加描述，如：

     @ApiOperation("通過並執行訂單")
    @PreAuthorize("hasRole('ROLE_ADMIN')") // super是我們在MyUserDetailsService中賦予admin用戶的。
    @GetMapping("apply")
    public String applyOrder(){
        return productService.reduceInventory();
    }

5. 啓動項目，訪問 http://localhost:8081/doc.html。
   首頁，是不是比默認的樣式好看多了！
   
   細節：
   
6. 測試接口調試功能，隨便打開一個接口，訪問。
   
   成功得到響應，比postman絲滑多了。

四、Swagger常用註解

• @Api()用於類；
  表示標識這個類是swagger的資源。
  屬性：tags，表示說明。

• @ApiOperation()用於方法；
  表示一個接口方法。
  屬性：value用於方法描述，notes用於提示內容。

• @ApiParam()用於方法，參數，字段說明；
  對參數的添加元數據。
  屬性：name–參數名,value–參數說明,required–是否必填。

• @ApiModel()用於類
  表示對類進行說明，用於參數用實體類接收。

• @ApiModelProperty()用於方法，字段
  對實體類中字段的描述。
  value–字段說明
  name–重寫屬性名字
  dataType–重寫屬性類型
  required–是否必填
  example–舉例說明
  hidden–隱藏

五、demo地址

https://github.com/flyChineseBoy/lel-mall/tree/master/mall08

下一節，我們繼續來看Spring Security分佈式場景下的應用。