springboot系列十三、springboot集成swaggerUI

一、Swagger介紹

Swagger能成為最受歡迎的REST APIs文檔生成工具之一，有以下幾個原因：

• Swagger 可以生成一個具有互動性的API控制台，開發者可以用來快速學習和嘗試API。
• Swagger 可以生成客戶端SDK代碼用於各種不同的平台上的實現。
• Swagger 文件可以在許多不同的平台上從代碼注釋中自動生成。
• Swagger 有一個強大的社區，里面有許多強悍的貢獻者。

Swagger 文檔提供了一個方法，使我們可以用指定的 JSON 或者 YAML 摘要來描述你的 API，包括了比如 names、order 等 API 信息。

你可以通過一個文本編輯器來編輯 Swagger 文件，或者你也可以從你的代碼注釋中自動生成。各種工具都可以使用 Swagger 文件來生成互動的 API 文檔。

二、配置及使用Swagger

1、引入依賴

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

2、添加配置類：SwaggerConfig.java

package com.example.demo.config;
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.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger2配置類
 * 在與spring boot集成時，放在與Application.java同級的目錄下。
 * 通過@Configuration注解，讓Spring來加載該類配置。
 * 再通過@EnableSwagger2注解來啟用Swagger2。
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

    /**
     * 創建API應用
     * apiInfo() 增加API相關信息
     * 通過select()函數返回一個ApiSelectorBuilder實例,用來控制哪些接口暴露給Swagger來展現，
     * 本例采用指定掃描的包路徑來定義指定要建立API的目錄。
     *
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.demo"))
                .paths(PathSelectors.any())
                .build();
    }

    /**
     * 創建該API的基本信息（這些基本信息會展現在文檔頁面中）
     * 訪問地址：http://項目實際地址/swagger-ui.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring Boot中使用Swagger2構建RESTful APIs")
                .description("更多請關注:博客園小人物的奮斗")
                .termsOfServiceUrl("http://www.cnblogs.com/wangzhuxing")
                .contact("xing")
                .version("1.0")
                .build();
    }
}

3、使用示例

1、注解Controller類

@Controller
@RequestMapping("/User")
@Api(description = "測試swagger注解的demo")
public class HelloWorldController {

　　@ResponseBody
　　@RequestMapping(value = "/getAllUser" ,method = RequestMethod.POST)
　　@ApiOperation(value = "獲取用戶信息",notes = "返回單個用戶信息")
　　public List<UserPO> getAllUser(@ApiParam(required = false) @RequestBody User user) {
    　　userService.addUser();
    　　return userService.findAll();
　　}

}

2、注解入參和出參

package com.example.demo.bean;
import io.swagger.annotations.ApiModelProperty;
import java.io.Serializable;

public class User implements Serializable {
    @ApiModelProperty(value = "用戶id" ,example = "11")
    private Long uid;
    @ApiModelProperty(value = "用戶姓名",example = "小明")
    private String name;
    @ApiModelProperty(value = "用戶年齡",example = "25")
    private Integer age;
    public Long getUid() {
        return uid;
    }
    public void setUid(Long uid) {
        this.uid = uid;
    }
    public String getName() {
        return name;
    }
    public void setName(String name) {
        this.name = name;
    }
    public Integer getAge() {
        return age;
    }
    public void setAge(Integer age) {
        this.age = age;
    }
}

4、驗證效果

訪問：http://192.168.1.100:8080/swagger-ui.html

 三、常見用法和說明

1. @Api：用在類上，說明該類的作用。
2. @ApiOperation：注解來給API增加方法說明。
3. @ApiImplicitParams : 用在方法上包含一組參數說明。
4. @ApiImplicitParam：用來注解來給方法入參增加說明。
5. @ApiResponses：用於表示一組響應

6. @ApiModel：描述一個Model的信息（一般用在請求參數無法使用@ApiImplicitParam注解進行描述的時候）

       l   @ApiModelProperty：描述一個model的屬性

7. @ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應信息

           l   code：數字，例如400

    　　l   message：信息，例如"請求參數沒填好"

    　　l   response：拋出異常的類  

 

 Swagger是一組開源項目，其中主要要項目如下：

1.   Swagger-tools:提供各種與Swagger進行集成和交互的工具。例如模式檢驗、Swagger 1.2文檔轉換成Swagger 2.0文檔等功能。

2.   Swagger-core: 用於Java/Scala的的Swagger實現。與JAX-RS(Jersey、Resteasy、CXF...)、Servlets和Play框架進行集成。

3.   Swagger-js: 用於JavaScript的Swagger實現。

4.   Swagger-node-express: Swagger模塊，用於node.js的Express web應用框架。

5.   Swagger-ui：一個無依賴的HTML、JS和CSS集合，可以為Swagger兼容API動態生成優雅文檔。

6.   Swagger-codegen：一個模板驅動引擎，通過分析用戶Swagger資源聲明以各種語言生成客戶端代碼。