SpringBoot入門實踐(八)-使用Swagger2構建強大的API文檔

 個人博客：蘭陵笑笑生,歡迎瀏覽博客！

 上一章 SpringBoot入門實踐(七)-Spring-Data-JPA實現數據訪問當中,咱們介紹瞭如何在項目中使用 Spring Data JPA來進行數據庫的訪問。本章將繼續探索springBoot的其餘功能，如何快速高效的構建在線的API文檔。

一 、前言

 現在先後端分離，那麼在先後端對接的時候少不了接口的文檔，過去咱們都是手寫一個wold文檔，我相信做爲一個寫代碼的，最不肯意的就是寫各種的文檔。固然接口文檔是必須的。可是咱們手動維護的API文檔在效率方面的確比較慢。並且還容易出錯，最最要命的是隨着項目的迭代，接口在不斷的改變，實時的更新接口文檔，是一件很分神的事情，今天咱們就簡單的介紹一個如何使用Swagger2快速的生成在線文檔。

2、 簡介

 在Swagger的官方網站上https://swagger.io/ 是這樣據介紹的，Swagger是實現了OpenApi標準的文檔使用工具，包含了各類開源的工具集。

• Swagger Core 用於生成Swagger的API規範的事例
• Swagger UI 生成一個界面，咱們這裏就會用到。
• SwaggerHub API設計和文檔化
• ...

三 、快速上手

3.1 引入依賴

 在構建好Restful API 後，咱們首先在pom.xml文件中引入Swagger2和Swagger UI的依賴：

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

3.2 Swagger2的配置

import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
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.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Swagger2Conf {

    /**
     * 控制http://localhost:8081/swagger-ui.html#/的顯示
     * @return
     */
    @Bean
    public Docket controllerApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        .title("標題：某公司_接口文檔")
                        .description("描述：用於XXXX功能,具體包括XXX,XXX模塊...")
                        .contact(new Contact("Socks", null, null))
                        .version("版本號:1.0")
                        .build())
                .select()
                //選擇的包名
                .apis(RequestHandlerSelectors.basePackage("com"))
                .paths(PathSelectors.any())
                .build();
    }
}

3.3 訪問地址

• http://localhost:8081/swagger-ui.html#/ 是以下的界面
• http://localhost:8081/v2/api-docs 是返回的接口的json

到這裏，swagger2的應用能夠說快速的入門，可使用了，可是咱們可能須要對Controller、方法作一些說明，咱們能夠經過如下額API精細化管理能夠實現。

3.4 API精細化管理

 首先的介紹幾個經常使用的註解：

3.4.1 @Api :添加在Controller控制器上，用來解釋當前的控制器

• value：貌似沒什麼用
• tags：描述這個控制器的，
• protocols：協議類型：http

• hidden：沒什麼用

  @Api(value = "value", tags = "用戶管理", hidden = true)
  @RestController
  @RequestMapping("/api/v1/user")
  public class UserController {
  ....
  }

3.4.2 @ApiOperation:註解添加在方法上，用來解釋當前的方法，包括用戶返回值

• value api的解釋
• notes api的注意事項
• response 返回的類型等

3.4.3 @ApiIgnore: 做用在REST API控制器方法上，則該API不會被顯示出來：

@ApiOperation(value = "刪除列表", notes = "注意", response = HttpResponse.class)
    @ApiIgnore
    @DeleteMapping("/delete/{id}")
    public HttpResponse delete(@PathVariable Long id) {
        userMap.remove(id);
        return HttpResponse.ok();
    }

3.4.4 @ApiImplicitParams和@ApiImplicitParam ，用來解釋方法的參數，

@ApiImplicitParams是能夠包含多個@ApiImplicitParam，如

/**
     * 列表請求
     * @return
     */
    @ApiOperation(value = "用戶列表",notes = "注意",response = HttpResponse.class)
    @RequestMapping(path = "/list",method = RequestMethod.PUT, 
    consumes = "application/json")
    @ApiImplicitParams({
            @ApiImplicitParam(name="userName",value = "用戶名稱"),
            @ApiImplicitParam(name="age",value = "用戶年齡")
    })
    public HttpResponse list(String userName ,Integer age) {
        List<User> user = new ArrayList<>(userMap.values());
        return HttpResponse.ok().setData(user);
    }

這樣API文檔就豐富了不少：

3.4.5 POJO 對象解釋

 在生成的在線API文檔中，不少時候咱們須要對POJO中的字段作一些解釋，好比下圖的User添加一個描述，對每一個字段添加一個描述，以及他的類型作一個解釋，這裏固然也可以使用Swagger2的其餘2個註解：@ApiModel和 @ApiModelProperty，沒有使用註解的時候以下圖：

3.4.5.1 : @ApiModel 添加在POJO 類上

• value：默認是類名
• description：對當前的POJO的描述

3.4.5.1：@ApiModelProperty

• name：屬性，默認pojo屬性
• value：值
• nodtes：注意事項
• dataType：屬性類型
• required：是否必須
• allowEmptyValue ：是否容許空置
• allowableValues :容許的值

package com.miroservice.chapter2.pojo;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel(value = "user",description = "用戶")
public class User {
    
    @ApiModelProperty(value = "用戶ID",notes = "notes",dataType = "long",required = false,allowEmptyValue = true)
    private Long id;
    
    @ApiModelProperty(value ="用戶名稱",notes = "notes",dataType = "String",required = false,allowEmptyValue = true)
    private String userName;

    @ApiModelProperty("用戶年齡")
    private Long age;
    ...
}

這樣保存的用戶的每一個屬性都有了解釋：

3.5 生產環境關閉Swagger2

 咱們使用Swagger2是爲了方便開發，可是如在把這樣的文檔在生產環境開啓，那我估計過不了多久工做就沒了，如何才能在正式環境禁止使用Swagger2呢，其實很簡單。咱們能夠在配置swagger的使用，添加一個註解：

@ConditionalOnProperty，並經過配置文件配置swagger.enable=true的時候，纔開啓swagger，以下配置：

@Configuration
@EnableSwagger2
@ConditionalOnProperty(name = "swagger.enable", havingValue = "true")
public class Swagger2Conf {

    /**
     * 控制http://localhost:8081/swagger-ui.html#/的顯示
     * @return
     */
    @Bean
    public Docket controllerApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        .title("標題：某公司_接口文檔")
                        .description("描述：用於XXXX功能,具體包括XXX,XXX模塊...")
                        .contact(new Contact("Socks", null, null))
                        .version("版本號:1.0")
                        .build())
                .select()
                //選擇的包名
                .apis(RequestHandlerSelectors.basePackage("com"))
                .paths(PathSelectors.any())
                .build();
    }
}

四 、總結

 這一篇文章簡單的介紹了springBoot如何集成Swagger2快速的構建在線的API文檔，包括各類註解的詳細的解釋，固然Swagger2的強大之處不只於此，還提供了更多擴展的功能，包括API分組，爲每一個API配置Token，生成靜態的文檔等，有興趣的能夠本身深刻研究，本章的介紹對於平時的開發應該是夠用了。

 以上就是本期的分享，你還能夠關注本博客的#Spring Boot入門實踐系列!#

本文由博客一文多發平臺 OpenWrite 發佈！
個人博客[蘭陵笑笑生] ( http://www.hao127.com.cn/),歡...！