如何在Spring Boot中對Swagger進行配置

如何在Spring Boot中對Swagger進行配置？相信很多沒有經(jīng)驗的人對此束手無策，為此本文總結(jié)了問題出現(xiàn)的原因和解決方法，通過這篇文章希望你能解決這個問題。

Swagger Inspector的建立是為了解決開發(fā)者的三個主要目標。

• 執(zhí)行簡單的API測試

• 生成OpenAPI文檔

• 探索新的API功能

下面來具體介紹，如果在Spring Boot中使用Swagger2。

添加Swagger2依賴

在pom.xml中加入Swagger2的依賴

 <!-- Swagger API-->
    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger2</artifactId>
      <version>2.2.2</version>
    </dependency>
    <dependency>
      <groupId>io.springfox</groupId>
      <artifactId>springfox-swagger-ui</artifactId>
      <version>2.2.2</version>
    </dependency>

創(chuàng)建Swagger2配置類

在HrabbitAdminApplication.java子包下創(chuàng)建Swagger2的配置類Swagger2。

通過@Configuration注解，讓Spring來加載該類配置。再通過@EnableSwagger2注解來啟用Swagger2。

再通過createRestApi函數(shù)創(chuàng)建Docket的Bean之后，apiInfo()用來創(chuàng)建該Api的基本信息（這些基本信息會展現(xiàn)在文檔頁面中）。select()函數(shù)返回一個ApiSelectorBuilder實例用來控制哪些接口暴露給Swagger來展現(xiàn)，包含注解的方式來確定要顯示的接口，當然也可以通過包掃描的方式來確定要顯示的包的接口。

/**
 * 配置Swagger
 *
 * @Auther: hrabbit
 * @Date: 2018-12-17 6:43 PM
 * @Description:
 */
@Configuration
@EnableSwagger2
public class SwaggerConfig {

  @Bean
  public Docket createRestApi() {
    return new Docket(DocumentationType.SWAGGER_2)
        .apiInfo(apiInfo())
        .select()
        .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))             //這里采用包含注解的方式來確定要顯示的接口
        //.apis(RequestHandlerSelectors.basePackage("com.hrabbit.admin.modual.system.controller"))  //這里采用包掃描的方式來確定要顯示的接口
        .paths(PathSelectors.any())
        .build();
  }

  private ApiInfo apiInfo() {
    return new ApiInfoBuilder()
        .title("Hrabbit-Admin Doc")
        .description("Guns Api文檔")
        .termsOfServiceUrl("https://gitee.com/hrabbit/hrabbit-admin")
        .contact("hrabbit")
        .version("1.0")
        .build();
  }

}

添加文檔內(nèi)容

我們通過@Api說明Controller，@ApiOperation注解來給API增加說明、通過@ApiImplicitParams、@ApiImplicitParam注解來給參數(shù)增加說明。

/**
 * 系統(tǒng)用戶
 *
 * @Auther: hrabbit
 * @Date: 2018-12-17 6:21 PM
 * @Description:
 */
@Controller
@RequestMapping("user")
@Api(value = "系統(tǒng)用戶")
public class SysUserController {

  @Autowired
  private SysUserService sysUserService;

  /**
   * 根據(jù)id獲取用戶信息
   *
   * @return
   */
  @RequestMapping("/",method = RequestMethod.GET)
  @ResponseBody
  @ApiOperation(value = "進入到主頁")
  public Object index() {
    return sysUserService.selectById(1L);
  }

  /**
   * 創(chuàng)建用戶信息
   *
   * @param user
   * @return
   */
  @ApiOperation(value = "創(chuàng)建用戶", notes = "根據(jù)SysUser對象創(chuàng)建用戶")
  @ApiImplicitParam(name = "user", value = "用戶詳細實體user", required = true, dataType = "SysUser")
  @RequestMapping(value = "", method = RequestMethod.POST)
  public String postUser(@RequestBody SysUser user) {
    return "success";
  }

  /**
   * 修改用戶信息
   *
   * @param id
   * @param user
   * @return
   */
  @ApiOperation(value = "更新用戶詳細信息", notes = "根據(jù)id更新系統(tǒng)用戶")
  @ApiImplicitParams({
      @ApiImplicitParam(name = "id", value = "用戶ID", required = true, dataType = "Long"),
      @ApiImplicitParam(name = "user", value = "用戶詳細實體sysUser", required = true, dataType = "SysUser")
  })
  @RequestMapping(value = "/{id}", method = RequestMethod.PUT)
  public String putUser(@PathVariable Long id, @RequestBody SysUser user) {
    return "success";
  }

}

完成上述代碼添加上，啟動Spring Boot程序，訪問：http://localhost:8080/swagger-ui.html
。就能看到前文所展示的RESTful API的頁面。我們可以再點開具體的API請求，以POST類型的/user請求為例，可找到上述代碼中我們配置的Notes信息以及參數(shù)user的描述信息，如下圖所示。

API文檔訪問與調(diào)試

在上圖請求的頁面中，我們看到user的Value是個輸入框？是的，Swagger除了查看接口功能外，還提供了調(diào)試測試功能，我們可以點擊上圖中右側(cè)的Model Schema（黃色區(qū)域：它指明了User的數(shù)據(jù)結(jié)構(gòu)），此時Value中就有了user對象的模板，我們只需要稍適修改，點擊下方“Try it out！”按鈕，即可完成了一次請求調(diào)用！

看完上述內(nèi)容，你們掌握如何在Spring Boot中對Swagger進行配置的方法了嗎？如果還想學到更多技能或想了解更多相關內(nèi)容，歡迎關注億速云行業(yè)資訊頻道，感謝各位的閱讀！