知識改變命運调鬓，擼碼使我快樂，你的發(fā)跡線還好嗎酌伊？

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

本篇文章對應(yīng)源碼碼云（Gitee）倉庫

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

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

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

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

前言

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

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

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

可配置參數(shù)一覽

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

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

創(chuàng)建示例項目

我們先來創(chuàng)建一個SpringBoot應(yī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)值员帮，下面是修改了版本號、標(biāo)題的配置：

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

測試控制器

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

/**
 * 示例控制器
 *
 * @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)實體示例
     */
    @ApiModel
    @Data
    @AllArgsConstructor
    @NoArgsConstructor
    public static class UserResponse {
        @ApiModelProperty(value = "用戶名")
        private String name;
        @ApiModelProperty(value = "年齡")
        private Integer age;
    }
}

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

運行測試

啟動本章項目源碼袋毙，訪問：http://localhost:8080/swagger-ui.html 查看運行效果型檀，如下圖所示：

image

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

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

敲黑板皆看，劃重點

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

代碼示例

如果您喜歡本篇文章請為源碼倉庫點個Star无埃，謝謝！ＰА录语！
本篇文章示例源碼可以通過以下途徑獲取，目錄為apiboot-swagger-describe-the-interface：

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

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