Swagger在Springboot項目中的使用

一、Swagger的歷史背景

  Swagger最初是一種簡單的設計規範，用於2010年設計Restful API。後來由規範和開源工具組成的Swagger項目非常受歡迎，形成了一個龐大的社區工具生態系統。2015年Swagger被SmartBear收購，並被捐贈給Linux基金會。

二、Swagger的作用

  說到Swagger的作用，就必須說到開發現狀：現在項目的開發基本都實現了前後端分離，後端控制數據的修改以及功能邏輯構建，前端做操作UI控制和頁面渲染，後端與前端進行接口對接的時候都會使用到接口文檔。一般我們選擇一些接口文檔管理工具，例如：RAP、DOClever、Apizza……

  Swagger也屬於一種接口文檔管理工具，支持整個API的生命週期（設計和文檔到測試和部署），號稱是“世界上最流行的API框架”。

三、Swagger的使用

1.創建Springboot項目

2.導入依賴

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

3.編寫Swagger配置文件

package org.magic.swagger.config;

import java.util.ArrayList;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
//開啓Swagger
@EnableSwagger2
public class SwaggerConfig {

  @Bean
  public Docket docket(Environment environment) {

    //設置要顯示的Swagger環境(開發環境和測試環境會顯示swagger，上線之後不顯示swagger)
    Profiles profiles=Profiles.of("dev","test");
    boolean flag = environment.acceptsProfiles(profiles);

    return new Docket(DocumentationType.SWAGGER_2)
        .groupName("無關痛癢")
        .apiInfo(apiInfo())
        //是否開啓swagger，如果爲false則Swagger在瀏覽器中無法訪問
        .enable(true)
        .select()
        //掃描該包下面的註解
        .apis(RequestHandlerSelectors.basePackage("org.magic.swagger.controller"))
        .build();
  }

  //配置Swagger信息
  private ApiInfo apiInfo() {
    //作者信息
    Contact contact = new Contact("無關痛癢", "https://blog.csdn.net/qq_43655835", "[email protected]");
    return new ApiInfo("Swagger API文檔",
        "以下接口屬於新項目---點餐系統",
        "1.0",
        "https://blog.csdn.net/qq_43655835",
        contact,
        "Apache 2.0",
        "http://www.apache.org/licenses/LICENSE-2.0",
        new ArrayList());
  }

4. Swagger分組

  在上面的配置中有一個.groupName(”無關痛癢“),在Swagger-ui中所顯示的位置在右上角：

當團隊中有多人進行協同開發的時候，每個人所寫的接口文檔不一樣，所以我們可以使用swagger進行分組，還是在SwaggerConfig配置類中進行配置：

package org.magic.swagger.config;

import java.util.ArrayList;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.env.Environment;
import org.springframework.core.env.Profiles;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
//開啓Swagger
@EnableSwagger2
public class SwaggerConfig {

  @Bean
  public Docket docket(Environment environment) {

    //設置要顯示的Swagger環境(開發環境和測試環境會顯示swagger，上線之後不顯示swagger)
    Profiles profiles=Profiles.of("dev","test");
    boolean flag = environment.acceptsProfiles(profiles);

    return new Docket(DocumentationType.SWAGGER_2)
        .groupName("無關痛癢")
        .apiInfo(apiInfo())
        //是否開啓swagger，如果爲false則Swagger在瀏覽器中無法訪問
        .enable(true)
        .select()
        //掃描該包下面的註解
        .apis(RequestHandlerSelectors.basePackage("org.magic.swagger.controller"))
        .build();
  }

  //配置Swagger信息
  private ApiInfo apiInfo() {
    //作者信息
    Contact contact = new Contact("無關痛癢", "https://blog.csdn.net/qq_43655835", "[email protected]");
    return new ApiInfo("Swagger API文檔",
        "以下接口屬於新項目---點餐系統",
        "1.0",
        "https://blog.csdn.net/qq_43655835",
        contact,
        "Apache 2.0",
        "http://www.apache.org/licenses/LICENSE-2.0",
        new ArrayList());
  }

  /**
   * Swagger文檔分組，多人協同開發
   */
  @Bean
  public Docket docket_zhang(){
    return  new Docket(DocumentationType.SWAGGER_2).groupName("張三");
  }

  @Bean
  public Docket docket_li(){
    return  new Docket(DocumentationType.SWAGGER_2).groupName("李四");
  }
}

  比如現在還有張三和李四都是一個開發小組的，那直接在SwaggerConfig配置文件中繼續new一個新的Docket並進行配置就行了（類似一個下拉菜單）：

5.常用的註解

註解	描述
@ApiModel（String description）	用於實體類上，對實體類進行描述
@ApiModelProperty(String description)	用於實體類屬性上，對實體類屬性進行描述

package org.magic.swagger.entiy;

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

@ApiModel("書籍實體類")
public class Book {

  @ApiModelProperty("書名")
  public String bookName;

  @ApiModelProperty("作者")
  private String author;

  public String getBookName() {
    return bookName;
  }

  public void setBookName(String bookName) {
    this.bookName = bookName;
  }

  public String getAuthor() {
    return author;
  }

  public void setAuthor(String author) {
    this.author = author;
  }
}

註解	描述
@ApiOperation(String description)	用於controller中的方法上，對方法進行描述
@ApiParam(String description)	用於描述入參
@Api(tags="")	用於描述類信息

package org.magic.swagger.controller;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import java.util.ArrayList;
import java.util.List;
import org.magic.swagger.entiy.Book;
import org.springframework.web.bind.annotation.DeleteMapping;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.PutMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@Api("書籍模塊")
public class BookController {

  private static List<Book> bookList = new ArrayList<>();

  @PostMapping("/insertBook")
  @ApiOperation("插入書籍信息")
  public Object insertBook(@ApiParam("書籍信息") Book book) {
    bookList.add(book);
    return bookList;
  }

  @GetMapping("/queryBooks")
  @ApiOperation("查詢書籍list")
  public Object queryBookByAuthor() {
    return bookList;
  }

  @PutMapping("/updateBookByAuthor/{author}/{bookName}")
  @ApiOperation("根據作者名稱修改書籍信息")
  public Object updateBookByAuthor(@ApiParam("作者名稱") @PathVariable String author,
                                    @ApiParam("修改後的書籍名稱") @PathVariable String bookName) {

    for (Book book : bookList) {
      if (book.getAuthor().equals(author)) {
          book.setBookName(bookName);
          return book;
      }
    }
    return null;
  }


  @DeleteMapping("/removeBook/{author}")
  @ApiOperation("根據作者刪除書籍")
  public Object removeBookByAuthor(@ApiParam("作者名稱") @PathVariable String author) {
    for (Book book : bookList) {
      if (book.getAuthor().equals(author)) {
        bookList.remove(book);
        return "刪除成功";
      }
    }
    return "沒有刪除任何數據";
  }


}

6. 使用Swagger測試

查看Swagger-ui（http://localhost:8082/swagger-ui.html）

在Swagger-ui中打開需要測試的接口：點擊Try it out，輸入測試入參：

然後查看響應結果：