快捷導(dǎo)航

Spring Boot整合Swagger2的完整步驟詳解

更新時(shí)間：2018年07月10日 14:55:15 作者：苦水潤(rùn)喉

這篇文章主要給大家介紹了關(guān)于Spring Boot整合Swagger2的完整步驟，文中通過(guò)示例代碼將整合的步驟一步步介紹的非常詳細(xì)，對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值，需要的朋友們下面隨著小編來(lái)一起學(xué)習(xí)學(xué)習(xí)吧

一、Swagger概述

Swagger是一組圍繞OpenAPI規(guī)范構(gòu)建的開(kāi)源工具，可幫助設(shè)計(jì)、構(gòu)建、記錄和使用REST API。

簡(jiǎn)單說(shuō)下，它的出現(xiàn)就是為了方便進(jìn)行測(cè)試后臺(tái)的restful形式的接口，實(shí)現(xiàn)動(dòng)態(tài)的更新，當(dāng)我們?cè)诤笈_(tái)的接口

修改了后，swagger可以實(shí)現(xiàn)自動(dòng)的更新，而不需要認(rèn)為的維護(hù)這個(gè)接口進(jìn)行測(cè)試。

二、Swagger常用注解

swagger通過(guò)注解表明該接口會(huì)生成文檔，包括接口名、請(qǐng)求方法、參數(shù)、返回信息的等等。

@Api：修飾整個(gè)類(lèi)，描述Controller的作用
@ApiOperation：描述一個(gè)類(lèi)的一個(gè)方法，或者說(shuō)一個(gè)接口
@ApiParam：?jiǎn)蝹€(gè)參數(shù)描述
@ApiModel：用對(duì)象來(lái)接收參數(shù)
@ApiProperty：用對(duì)象接收參數(shù)時(shí)，描述對(duì)象的一個(gè)字段
@ApiResponse：HTTP響應(yīng)其中1個(gè)描述
@ApiResponses：HTTP響應(yīng)整體描述
@ApiIgnore：使用該注解忽略這個(gè)API
@ApiError ：發(fā)生錯(cuò)誤返回的信息
@ApiParamImplicitL：一個(gè)請(qǐng)求參數(shù)
@ApiParamsImplicit 多個(gè)請(qǐng)求參數(shù)

三、SpringBoot整合Swagger

3.1 添加依賴(lài)

<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>

3.2 添加SwaggerConfiguration

通過(guò)@Configuration注解，表明它是一個(gè)配置類(lèi)，@EnableSwagger2開(kāi)啟swagger2。

apiINfo()配置一些基本的信息。apis()指定掃描的包會(huì)生成文檔。

再通過(guò)createRestApi函數(shù)創(chuàng)建Docket的Bean之后，apiInfo()用來(lái)創(chuàng)建該Api的基本信息（這些基本信息會(huì)
展現(xiàn)在文檔頁(yè)面中）。select()函數(shù)返回一個(gè)ApiSelectorBuilder實(shí)例用來(lái)控制哪些接口暴露給Swagger來(lái)
展現(xiàn)，本例采用指定掃描的包路徑來(lái)定義，Swagger會(huì)掃描該包下所有Controller定義的API，并產(chǎn)生文檔內(nèi)容
（除了被@ApiIgnore指定的請(qǐng)求）。

package com.lance.learn.springbootswagger.configuration;

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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * @author lance(ZYH)
 * @function Swagger啟動(dòng)配置類(lèi)
 * @date 2018-07-09 21:24
 */
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

 /**
  * swagger2的配置文件，這里可以配置swagger2的一些基本的內(nèi)容，比如掃描的包等等
  * @return
  */
 @Bean
 public Docket createRestfulApi(){
  return new Docket(DocumentationType.SWAGGER_2)
    .pathMapping("/")
    .select()
    .apis(RequestHandlerSelectors.basePackage("com.lance.learn.springbootswagger.controller")) //暴露接口地址的包路徑
    .paths(PathSelectors.any())
    .build();
 }

 /**
  * 構(gòu)建 api文檔的詳細(xì)信息函數(shù),注意這里的注解引用的是哪個(gè)
  * @return
  */
 private ApiInfo apiInfo(){
  return new ApiInfoBuilder()
    //頁(yè)面標(biāo)題
    .title("Spring Boot 測(cè)試使用 Swagger2 構(gòu)建RESTful API")
    //創(chuàng)建人
    .contact(new Contact("LanveToBigData", "http://www.cnblogs.com/zhangyinhua/", "917484312@qq.com"))
    //版本號(hào)
    .version("1.0")
    //描述
    .description("API 描述")
    .build();
 }
}

3.3 Controller文檔內(nèi)容

描述主要來(lái)源于函數(shù)等命名產(chǎn)生，對(duì)用戶(hù)并不友好，我們通常需要自己增加一些說(shuō)明來(lái)豐富文檔內(nèi)容。

如下所示，我們通過(guò)@ApiOperation注解來(lái)給API增加說(shuō)明、通過(guò)@ApiImplicitParams、@ApiImplicitParam
注解來(lái)給參數(shù)增加說(shuō)明。

1）實(shí)例一

package com.lance.learn.springbootswagger.controller;

import com.lance.learn.springbootswagger.bean.Book;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;

import java.util.*;

/**
 * @author lance(ZYH)
 * @function
 * @date 2018-07-09 21:39
 */
@RestController
@RequestMapping(value = "/bookcurd")
public class BookController {
 Map<Long, Book> books = Collections.synchronizedMap(new HashMap<Long, Book>());

 @ApiOperation(value="獲取圖書(shū)列表", notes="獲取圖書(shū)列表")
 @RequestMapping(value={""}, method= RequestMethod.GET)
 public List<Book> getBook() {
  List<Book> book = new ArrayList<>(books.values());
  return book;
 }

 @ApiOperation(value="創(chuàng)建圖書(shū)", notes="創(chuàng)建圖書(shū)")
 @ApiImplicitParam(name = "book", value = "圖書(shū)詳細(xì)實(shí)體", required = true, dataType = "Book")
 @RequestMapping(value="", method=RequestMethod.POST)
 public String postBook(@RequestBody Book book) {
  books.put(book.getId(), book);
  return "success";
 }
 @ApiOperation(value="獲圖書(shū)細(xì)信息", notes="根據(jù)url的id來(lái)獲取詳細(xì)信息")
 @ApiImplicitParam(name = "id", value = "ID", required = true, dataType = "Long",paramType = "path")
 @RequestMapping(value="/{id}", method=RequestMethod.GET)
 public Book getBook(@PathVariable Long id) {
  return books.get(id);
 }

 @ApiOperation(value="更新信息", notes="根據(jù)url的id來(lái)指定更新圖書(shū)信息")
 @ApiImplicitParams({
   @ApiImplicitParam(name = "id", value = "圖書(shū)ID", required = true, dataType = "Long",paramType = "path"),
   @ApiImplicitParam(name = "book", value = "圖書(shū)實(shí)體book", required = true, dataType = "Book")
 })
 @RequestMapping(value="/{id}", method= RequestMethod.PUT)
 public String putUser(@PathVariable Long id, @RequestBody Book book) {
  Book book1 = books.get(id);
  book1.setName(book.getName());
  book1.setPrice(book.getPrice());
  books.put(id, book1);
  return "success";
 }
 @ApiOperation(value="刪除圖書(shū)", notes="根據(jù)url的id來(lái)指定刪除圖書(shū)")
 @ApiImplicitParam(name = "id", value = "圖書(shū)ID", required = true, dataType = "Long",paramType = "path")
 @RequestMapping(value="/{id}", method=RequestMethod.DELETE)
 public String deleteUser(@PathVariable Long id) {
  books.remove(id);
  return "success";
 }

 @ApiIgnore//使用該注解忽略這個(gè)API
 @RequestMapping(value = "/hi", method = RequestMethod.GET)
 public String jsonTest() {
  return " hi you!";
 }
}

2）實(shí)例二

package com.lance.learn.springbootswagger.controller;

import com.lance.learn.springbootswagger.bean.User;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

import java.util.*;

/**
 * @author lance(ZYH)
 * @function
 * @date 2018-07-09 22:00
 */

@RestController
@RequestMapping(value="/users")
public class UserDetailController {
  static Map<Long, User> users = Collections.synchronizedMap(new HashMap<Long, User>());

  @ApiOperation(value="獲取用戶(hù)列表", notes="")
  @RequestMapping(value={""}, method= RequestMethod.GET)
  public List<User> getUserList() {
    List<User> r = new ArrayList<User>(users.values());
    return r;
  }

  @ApiOperation(value="創(chuàng)建用戶(hù)", notes="根據(jù)User對(duì)象創(chuàng)建用戶(hù)")
  @ApiImplicitParam(name = "user", value = "用戶(hù)詳細(xì)實(shí)體user", required = true, dataType = "User")
  @RequestMapping(value="", method=RequestMethod.POST)
  public String postUser(@RequestBody User user) {
    users.put(user.getId(), user);
    return "success";
  }

  @ApiOperation(value="獲取用戶(hù)詳細(xì)信息", notes="根據(jù)url的id來(lái)獲取用戶(hù)詳細(xì)信息")
  @ApiImplicitParam(name = "id", value = "用戶(hù)ID", required = true, dataType = "Long")
  @RequestMapping(value="/{id}", method=RequestMethod.GET)
  public User getUser(@PathVariable Long id) {
    return users.get(id);
  }

  @ApiOperation(value="更新用戶(hù)詳細(xì)信息", notes="根據(jù)url的id來(lái)指定更新對(duì)象，并根據(jù)傳過(guò)來(lái)的user信息來(lái)更新用戶(hù)詳細(xì)信息")
  @ApiImplicitParams({
      @ApiImplicitParam(name = "id", value = "用戶(hù)ID", required = true, dataType = "Long"),
      @ApiImplicitParam(name = "user", value = "用戶(hù)詳細(xì)實(shí)體user", required = true, dataType = "User")
  })
  @RequestMapping(value="/{id}", method=RequestMethod.PUT)
  public String putUser(@PathVariable Long id, @RequestBody User user) {
    User u = new User();
    users.put(id, u);
    return "success";
  }

  @ApiOperation(value="刪除用戶(hù)", notes="根據(jù)url的id來(lái)指定刪除對(duì)象")
  @ApiImplicitParam(name = "id", value = "用戶(hù)ID", required = true, dataType = "Long")
  @RequestMapping(value="/{id}", method=RequestMethod.DELETE)
  public String deleteUser(@PathVariable Long id) {
    users.remove(id);
    return "success";
  }
}