第二章：Swagger2

這篇具有很好參考價值的文章主要介紹了第二章：Swagger2。希望對大家有所幫助。如果存在錯誤或未考慮完全的地方，請大家不吝賜教，您也可以點擊"舉報違法"按鈕提交疑問。

背景介紹

什么是Swagger2

常用注解

SpringBoot整合Swagger2

生產(chǎn)環(huán)境下屏蔽Swagger2

修改Swagger2配置類

修改application.yml

使用maven package打包測試

運行測試

背景介紹

在團隊開發(fā)中，一個好的 API 文檔不但可以減少大量的溝通成本，還可以幫助一位新人快速上手業(yè)務(wù)。傳統(tǒng)的做法是由開發(fā)人員創(chuàng)建一份 RESTful API 文檔來記錄所有的接口細節(jié)，并在程序員之間代代相傳。這種做法存在以下幾個問題：

1）API 接口眾多，細節(jié)復(fù)雜，需要考慮不同的HTTP請求類型、HTTP頭部信息、HTTP請求內(nèi)容等，想要高質(zhì)量的完成這份文檔需要耗費大量的精力；

2）難以維護。隨著需求的變更和項目的優(yōu)化、推進，接口的細節(jié)在不斷地演變，接口描述文檔也需要同步修訂，可是文檔和代碼處于兩個不同的媒介，除非有嚴格的管理機制，否則很容易出現(xiàn)文檔、接口不一致的情況；

Swagger2 的出現(xiàn)就是為了從根本上解決上述問題。它作為一個規(guī)范和完整的框架，可以用于生成、描述、調(diào)用和可視化 RESTful 風(fēng)格的 Web 服務(wù)：

接口文檔在線自動生成，文檔隨接口變動實時更新，節(jié)省維護成本；

支持在線接口測試，不依賴第三方工具；

什么是Swagger2

Swagger2 是一個規(guī)范和完整的框架，用于生成、描述、調(diào)用和可視化Restful風(fēng)格的web服務(wù)，現(xiàn)在我們使用spring boot 整合它。作用：

接口的文檔在線自動生成；

功能測試；

常用注解

注解	描述
@Api	將類標記為 Swagger 資源。
@ApiImplicitParam	表示 API 操作中的單個參數(shù)。
@ApiImplicitParams	允許多個 ApiImplicitParam 對象列表的包裝器。
@ApiModel	提供有關(guān) Swagger 模型的其他信息。
@ApiModelProperty	添加和操作模型屬性的數(shù)據(jù)。
@ApiOperation	描述針對特定路徑的操作或通常是 HTTP 方法。
@ApiParam	為操作參數(shù)添加額外的元數(shù)據(jù)。
@ApiResponse	描述操作的可能響應(yīng)。
@ApiResponses	允許多個 ApiResponse 對象列表的包裝器。
@Authorization	聲明要在資源或操作上使用的授權(quán)方案。
@AuthorizationScope	描述 OAuth2 授權(quán)范圍。

SpringBoot整合Swagger2

導(dǎo)入依賴

<dependency>
 ?  <groupId>io.springfox</groupId>
 ?  <artifactId>springfox-swagger2</artifactId>
 ?  <version>2.9.2</version>
 ?  <exclusions>
 ? ? ?  <exclusion>
 ? ? ? ? ?  <artifactId>swagger-models</artifactId>
 ? ? ? ? ?  <groupId>io.swagger</groupId>
 ? ? ?  </exclusion>
 ?  </exclusions>
</dependency>
?
<dependency>
 ?  <groupId>com.github.xiaoymin</groupId>
 ?  <artifactId>swagger-bootstrap-ui</artifactId>
 ?  <version>1.8.5</version>
</dependency>
?
<!-- 使用1.5.22-->
<dependency>
 ?  <groupId>io.swagger</groupId>
 ?  <artifactId>swagger-models</artifactId>
 ?  <version>1.5.22</version>
</dependency>

創(chuàng)建Swagger配置類

@Configuration
//開啟Swagger2
@EnableSwagger2
//配置生產(chǎn)環(huán)境下不可用  dev(開發(fā))、test(測試)、prod(生產(chǎn))
@Profile({"dev","test"})
public class Swagger2Configuration extends WebMvcConfigurationSupport {
 ?  //api接口包掃描路徑
 ?  public static final String
 ? ? ? ? ?  SWAGGER_SCAN_BASE_PACKAGE = "com.lky.swagger2pro.controller";
 ?  //指定當前Swagger API文檔版本
 ?  public static final String VERSION = "1.0.0";
?
 ?  /**
 ? ? * 創(chuàng)建API應(yīng)用
 ? ? * apiInfo() 增加API相關(guān)信息
 ? ? * 通過select()函數(shù)返回一個ApiSelectorBuilder實例,用來控制哪些接口暴露給Swagger來展現(xiàn)，
 ? ? * 本例采用指定掃描的包路徑來定義指定要建立API的目錄。
 ? ? * @return
 ? ? */
 ?  @Bean
 ?  public Docket createRestApi() {
 ? ? ?  return new Docket(DocumentationType.SWAGGER_2)
 ? ? ? ? ? ? ?  // 接口文檔的基本信息
 ? ? ? ? ? ? ?  .apiInfo(apiInfo())
 ? ? ? ? ? ? ?  .select()
 ? ? ? ? ? ? ?  // 方法需要有ApiOperation注解才能生存接口文檔
 ? ? ? ? ? ? ?  //.apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
 ? ? ? ? ? ? ?  .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
 ? ? ? ? ? ? ?  // 路徑使用any風(fēng)格
 ? ? ? ? ? ? ?  .paths(PathSelectors.any())
 ? ? ? ? ? ? ?  .build();
 ?  }
?
 ?  /**
 ? ? * 創(chuàng)建該API的基本信息（這些基本信息會展現(xiàn)在文檔頁面中）
 ? ? * 訪問地址：http://項目實際地址/doc.html
 ? ? * @return
 ? ? */
 ?  private ApiInfo apiInfo() {
 ? ? ?  return new ApiInfoBuilder()
 ? ? ? ? ? ? ?  .title("SpringBoot中使用Swagger2構(gòu)建RestFul APIs")
 ? ? ? ? ? ? ?  .description("測試系統(tǒng)")
 ? ? ? ? ? ? ?  //.termsOfServiceUrl("http://www.**.com")
 ? ? ? ? ? ? ?  .version(VERSION)
 ? ? ? ? ? ? ?  .build();
 ?  }
?
 ?  @Override
 ?  protected void addResourceHandlers(ResourceHandlerRegistry registry) {
 ? ? ?  registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
 ? ? ?  registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
 ?  }
}

1) 完成以上配置之后，通過mybatis-generator生成model和mapper； 2) 創(chuàng)建IBookService及BookServiceImpl實現(xiàn)類； 3) 創(chuàng)建BookController

綜合案例

在自己的封裝代碼中去除對swagger分組接口的封裝,前沿技術(shù)+Shiro權(quán)限框架,java,spring boot,mybatis,文檔資料

@Api

@Api注解用在類上，說明該類的作用?？梢詷擞浺粋€Controller類做為swagger文檔資源。

屬性	說明
value	url的路徑值
tags	如果設(shè)置這個值、value的值會被覆蓋
produces	返回的格式類型例如："application/json, application/xml"
consumes	接收請求參數(shù)的類型例如："application/json, application/xml"
protocols	Possible values: http, https, ws, wss.
authorizations	高級特性認證時配置

案例演示

@RestController
@Api(value = "書本管理",tags = {"書本管理"}) //tags可以代替value屬性
@RequestMapping("/book")
public class BookController {
 ?  ...
}

@ApiOperation

@ApiOperation注解用在方法上，說明方法的作用，每一個url資源的定義。

屬性	說明
value	url的路徑值
tags	如果設(shè)置這個值、value的值會被覆蓋
produces	返回的格式類型例如："application/json, application/xml"
consumes	接收請求參數(shù)的類型例如："application/json, application/xml"
hidden	是否在文檔中顯示
notes	注釋說明
response	返回的對象
responseContainer	這些對象是有效的 "List", "Set" or "Map".，其他無效
responseReference	指定對響應(yīng)類型的引用。指定的引用可以是本地的，也可以是遠程的*將按原樣使用，并覆蓋任何指定的response()類
responseHeaders	響應(yīng)旁邊提供的可能標題列表
httpMethod	"GET", "HEAD", "POST", "PUT", "DELETE", "OPTIONS" and "PATCH"
code	http的狀態(tài)碼默認 200

案例演示

@ApiOperation(value = "查詢所有書本信息", notes = "查詢返回所有書本信息集合",
 ? ? ? ? ?  produces = "application/json")
@GetMapping(value="/queryAll")
public JsonResponseBody<List<Book>> queryAll(){
 ?  try {
 ? ? ?  return bookService.queryAll();
 ?  } catch (Exception e) {
 ? ? ?  e.printStackTrace();
 ? ? ?  return new JsonResponseBody<>(500,e.getMessage());
 ?  }
}

@ApiImplicitParam

@ApilmplicitParam 注解用來描述一個參數(shù)，可以配置參數(shù)的中文含義，也可以給參數(shù)設(shè)置默認值，這樣在接口測試的時候可以避免手動輸入；

屬性	說明
paramType	參數(shù)放在哪個地方
name	參數(shù)名稱
value	參數(shù)代表的含義
dataType	參數(shù)類型
dataTypeClass	參數(shù)類型
required	是否必要
defaultValue	參數(shù)的默認值

paramType

類型	作用
path	以地址的形式提交數(shù)據(jù)，用于restful接口。請求參數(shù)采用@PathVariable獲取
query	直接跟參數(shù)完成自動映射賦值。請求參數(shù)可采用@RequestParam獲取
body	以流的形式提交，僅支持POST。請求參數(shù)采用@RequestBody獲取
header	參數(shù)在request headers里邊提交。請求參數(shù)采用@RequestHeader獲取
form	以form表單的形式提交，僅支持POST。

案例演示

@ApiOperation(value="查詢單個書本信息",notes = "查詢單個書本信息")
@ApiImplicitParam(value="書本ID",name="bookid",required = true,dataType = "String",defaultValue = "8f46b5018a6811e9a9c528d24413c293" )
@GetMapping("/querySingleBook")
public Book querySingleBook(String bookid){
 ?  JsonResponseBody<Book> json = bookService.selectByPrimaryKey(bookid);
 ?  return json.getData();
}

@ApiImplicitParams

@ApilmplicitParams 如果有多個參數(shù)，則需要使用多個 @ApilmplicitParam 注解來描述，多個 @ApilmplicitParam 注解需要放在一個 @ApilmplicitParams 注解中；

案例演示

@ApiOperation(value = "新增書本信息", notes = "新增書本信息"
 ? ? ? ? ?  ,produces = "application/json",consumes = "application/json")
@ApiImplicitParams({
 ? ? ? ? ?  @ApiImplicitParam(name="bookname",value="書本名稱",required = true,dataType = "String"),
 ? ? ? ? ?  @ApiImplicitParam(name="price",value="書本價格",required = true,dataType = "Double"),
 ? ? ? ? ?  @ApiImplicitParam(name="booktype",value="書本類型",required = true,dataType = "String")
})
@PostMapping("/addBook")
public JsonResponseBody<?> addBook(@RequestParam String bookname,
 ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? @RequestParam Double price,
 ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? ? @RequestParam String booktype){
 ?  return bookService.insert(Book.builder()
 ? ? ?  .bookid(UUID.randomUUID().toString().replace("-",""))
 ? ? ?  .bookname(bookname)
 ? ? ?  .booktype(booktype)
 ? ? ?  .price(price)
 ? ? ?  .build());
}

@ApiModel和@ApiModelProperty

@ApiModel注解描述一個Model的信息（這種一般用在post創(chuàng)建的時候，使用@RequestBody這樣的場景，請求參數(shù)無法使用 @ApiImplicitParam注解進行描述的時候；

@ApiModelProperty注解描述一個model的屬性。

屬性	說明
value	字段說明
name	參數(shù)名稱
dataType	參數(shù)類型
hidden	在文檔中隱藏
required	是否必要
example	舉例說明
notes	注釋說明

案例演示

Controller

@ApiOperation(value="修改書本信息",notes = "修改書本信息")
@PostMapping("/editBook")
public JsonResponseBody<?> editBook(@RequestBody Book book){
 ?  return bookService.updateByPrimaryKey(book);
}

注意：在這里可以不使用@ApiImplicitParam標注Swagger中的參數(shù)信息，因為在這里的輸入?yún)?shù)是實體對象，而在實體對象中已經(jīng)使用@ApiModel和@ApiModelProperty注解進行了標識。

Book實體類

@Data
@Builder
@AllArgsConstructor
@NoArgsConstructor
@ApiModel(value="書本對象")
public class Book implements Serializable {
?
 ?  /**
 ? ? * 書本編號
 ? ? */
 ?  @ApiModelProperty(value="書本編號")
 ?  private String bookid;
?
 ?  /**
 ? ? * 書本名稱
 ? ? */
 ?  @ApiModelProperty(value="書本名稱")
 ?  private String bookname;
?
 ?  /**
 ? ? * 書本價格
 ? ? */
 ?  @ApiModelProperty(value="書本價格")
 ?  private Double price;
?
 ?  /**
 ? ? * 書本類型
 ? ? */
 ?  @ApiModelProperty(value="書本類型")
 ?  private String booktype;
?
 ?  private static final long serialVersionUID = 1L;
}

@ApiParam

作用在方法的參數(shù)上，用來描述接口的參數(shù)信息(一個參設(shè)置一個)

@ApiParam必須與@RequestParam、@PathVariable和@RequestHeader一起使用。

屬性	說明
name	參數(shù)名稱
value	參數(shù)簡單描述
defaultValue	描述參數(shù)默認值
required	是否為必傳參數(shù), false:非必傳; true:必傳
allowMultiple	指定參數(shù)是否可以通過多次出現(xiàn)來接收多個值
hidden	隱藏參數(shù)列表中的參數(shù)
example	非請求體(body)類型的單個參數(shù)示例
examples	@Example(value = @ExampleProperty(mediaType = “”, value = “”)) 參數(shù)示例，僅適用于請求體類型的請求

案例演示

@ApiOperation(value="新增書本信息1",notes="新增書本信息1")
@PostMapping("/addBooks")
public JsonResponseBody<?> addBooks(
            @ApiParam(name="bookName",value="bookName",required = true) @RequestParam("bookName") String bookName,
            @ApiParam(name="price",value="price",required = true) @RequestParam("price") float price,
            @ApiParam(name="bookType",value="bookType",required = true) @RequestParam("bookType") String bookType){
      System.out.println("bookName="+bookName+",price="+price+",bookType="+bookType);
    return new JsonResponseBody<>();
}

生產(chǎn)環(huán)境下屏蔽Swagger2

為了保證接口文檔的安全，禁用了生產(chǎn)環(huán)境的加載，具體說明請看：

參考地址：https://www.jianshu.com/p/fa3230ffb27c

一般生產(chǎn)環(huán)境是不能放開swagger的，這樣接口暴露在外網(wǎng)很不安全!!!

一般生產(chǎn)環(huán)境是不能放開swagger的，這樣接口暴露在外網(wǎng)很不安全!!!

一般生產(chǎn)環(huán)境是不能放開swagger的，這樣接口暴露在外網(wǎng)很不安全!!!

修改Swagger2配置類

添加@Profile注解，指明在何種環(huán)境下可以使用Swagger2，一般情況下只有在開發(fā)(dev)和測試(test)環(huán)境下才可以使用Swagger2；而在生產(chǎn)(dev)環(huán)境下不能使用Swagger2。

@Configuration
//開啟Swagger2
@EnableSwagger2
//配置生產(chǎn)環(huán)境下不可用  dev(開發(fā))、test(測試)、prod(生產(chǎn))
@Profile({"dev","test"})
public class Swagger2Configuration extends WebMvcConfigurationSupport {
    
    ...

    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("doc.html")
.addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

修改application.yml

修改application.yml文件，配置項目系統(tǒng)的運行環(huán)境（dev/test/prod）

spring:
  #配置swagger2生產(chǎn)和測試環(huán)境不可用
  profiles:
    active: prod

使用maven package打包測試

在自己的封裝代碼中去除對swagger分組接口的封裝,前沿技術(shù)+Shiro權(quán)限框架,java,spring boot,mybatis,文檔資料

運行測試

打開CMD，跳轉(zhuǎn)到target目錄，輸入命令：java -jar .\xxx.jar --spring.profiles.active=prod?？梢灾苯哟蜷_jar包修改application.yml配置文件中spring.profiles.active屬性切換運行環(huán)境，具體請參考以下配置：