知識(shí)改變命運(yùn)，擼碼使我快樂，你的發(fā)跡線還好嗎？

點(diǎn)贊再看，養(yǎng)成習(xí)慣

本篇文章對(duì)應(yīng)源碼碼云（Gitee）倉(cāng)庫(kù)

https://gitee.com/minbox-projects/api-boot-chapter，您的Star是給我最大動(dòng)力

接口文檔在前后分離的項(xiàng)目中是必不可少的一部分，文檔的編寫一直以來都是一件頭疼的事情，寫程序不寫注釋、不寫文檔這幾乎是程序員的通病，Swagger2的產(chǎn)生給廣大的程序員們帶來了曙光，只需要在接口類或者接口的方法上添加注解配置，就可以實(shí)現(xiàn)文檔效果，除了可以應(yīng)用到單體應(yīng)用，在微服務(wù)架構(gòu)中也是可以使用的，只需要整合zuul就可以實(shí)現(xiàn)各個(gè)服務(wù)的文檔整合。

本文所需ApiBoot相關(guān)鏈接：

• ApiBoot官網(wǎng)
• ApiBoot全組件系列文章
• ApiBoot Gitee源碼倉(cāng)庫(kù)（歡迎Contributor）
• ApiBoot GitHub源碼倉(cāng)庫(kù)（歡迎Contributor）

前言

ApiBoot Swagger內(nèi)部封裝了Swagger2，只需要一個(gè)注解@EnableApiBootSwagger就可以實(shí)現(xiàn)集成，使用起來非常簡(jiǎn)單。

ApiBoot Swagger提供了一系列的默認(rèn)配置，比如：文檔標(biāo)題、文檔描述、文檔版本號(hào)等，如果需要修改文檔的默認(rèn)配置，只需要在application.yml文件內(nèi)對(duì)應(yīng)配置參數(shù)即可實(shí)現(xiàn)自定義，告別了繁瑣的代碼配置，ApiBoot通過自動(dòng)化配置的方式來實(shí)現(xiàn)這一點(diǎn)，可以查看 ApiBootSwaggerAutoConfiguration 配置類源碼了解詳情。

ApiBoot Swagger支持在線調(diào)試集成OAuth2的接口，只需要在文檔界面通過 "Authorize"按鈕設(shè)置有效的AccessToken即可。

可配置參數(shù)一覽

ApiBoot Swagger之所以可以只需要一個(gè)注解就可以實(shí)現(xiàn)Swagger2的集成，其中難免有很多的配置參數(shù)在做支持，了解每一個(gè)配置參數(shù)的作用，我們才能進(jìn)行心應(yīng)手的自定義調(diào)整。

上面是常用的參數(shù)，更多配置參數(shù)詳見官方文檔：http://apiboot.minbox.io/zh-cn/docs/api-boot-swagger.html

創(chuàng)建示例項(xiàng)目

我們先來創(chuàng)建一個(gè)SpringBoot應(yīng)用程序，在項(xiàng)目的pom.xml文件內(nèi)添加ApiBoot的相關(guān)依賴，如下所示：

<dependencies>
  <dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
  </dependency>
  <dependency>
    <groupId>org.minbox.framework</groupId>
    <artifactId>api-boot-starter-swagger</artifactId>
  </dependency>

</dependencies>
<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.minbox.framework</groupId>
      <artifactId>api-boot-dependencies</artifactId>
      <version>2.2.1.RELEASE</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

啟用ApiBoot Swagger

通過@EnableApiBootSwagger注解來啟用ApiBoot Swagger，該注解可以配置在XxxApplication入口類上，也可以配置在被@Configuration注解修飾的配置類上。

@SpringBootApplication
@EnableApiBootSwagger
public class ApibootSwaggerDescribeTheInterfaceApplication {

    public static void main(String[] args) {
        SpringApplication.run(ApibootSwaggerDescribeTheInterfaceApplication.class, args);
    }

}

修改默認(rèn)配置

ApiBoot Swagger所提供的配置參數(shù)都可以在application.yml文件內(nèi)進(jìn)行設(shè)置或修改默認(rèn)值，下面是修改了版本號(hào)、標(biāo)題的配置：

# ApiBoot相關(guān)配置
api:
  boot:
    swagger:
      # 配置文檔標(biāo)題
      title: 接口文檔
      # 配置文檔版本
      version: v1.0

測(cè)試控制器

為了方便演示Swagger文檔的強(qiáng)大之處，我們來創(chuàng)建一個(gè)測(cè)試的控制器，使用Swagger提供的注解來描述測(cè)試接口，如下所示：

/**
 * 示例控制器
 *
 * @author 恒宇少年
 */
@RestController
@RequestMapping(value = "/user")
@Api(tags = "用戶控制器")
public class UserController {
    /**
     * 示例：
     * 根據(jù)用戶名查詢用戶基本信息
     *
     * @param name {@link UserResponse#getName()}
     * @return {@link UserResponse}
     */
    @GetMapping(value = "/{name}")
    @ApiOperation(value = "查詢用戶信息", response = UserResponse.class)
    @ApiResponse(code = 200, message = "success", response = UserResponse.class)
    public UserResponse getUser(@PathVariable("name") String name) {
        return new UserResponse(name, 25);
    }
    /**
     * 響應(yīng)實(shí)體示例
     */
    @ApiModel
    @Data
    @AllArgsConstructor
    @NoArgsConstructor
    public static class UserResponse {
        @ApiModelProperty(value = "用戶名")
        private String name;
        @ApiModelProperty(value = "年齡")
        private Integer age;
    }
}

注意：ApiBoot Swagger只是針對(duì)Swagger進(jìn)行了封裝，實(shí)現(xiàn)了快速集成，對(duì)內(nèi)部的注解以及配置不做修改。

運(yùn)行測(cè)試

啟動(dòng)本章項(xiàng)目源碼，訪問：http://localhost:8080/swagger-ui.html 查看運(yùn)行效果，如下圖所示：

image

當(dāng)我們點(diǎn)擊 "用戶控制器" 時(shí)可以展開該Controller內(nèi)定義的接口列表，每一個(gè)接口都提供了 "Try it out"（在線調(diào)試）功能。

本章并沒有集成OAuth2，在執(zhí)行在線調(diào)試時(shí)并不需要配置AccessToken。

敲黑板，劃重點(diǎn)

ApiBoot Swagger的實(shí)現(xiàn)主要?dú)w功于SpringBoot自定義Starter，根據(jù)配置參數(shù)進(jìn)行條件配置控制對(duì)象的實(shí)例化，通過@Import來導(dǎo)入Swagger所需要的配置類。

代碼示例

如果您喜歡本篇文章請(qǐng)為源碼倉(cāng)庫(kù)點(diǎn)個(gè)Star，謝謝！??！
本篇文章示例源碼可以通過以下途徑獲取，目錄為apiboot-swagger-describe-the-interface：

• Gitee：https://gitee.com/minbox-projects/api-boot-chapter

作者個(gè)人 博客
使用開源框架 ApiBoot 助你成為Api接口服務(wù)架構(gòu)師