Spring Boot：Spring Boot配置Swagger

由於Spring Boot能夠快速開發、便捷部署等特性，相信有很大一部分Spring Boot的使用者會用來構建RESTful API。而我們構建RESTful API的目的通常都是由於多終端的原因，這些終端會共用很多底層業務邏輯，因此我們會抽象出這樣一層來同時服務於多個移動端或者Web前端。

Swagger Inspector：測試API和生成OpenAPI的開發工具。Swagger Inspector的建立是為了解決開發者的三個主要目標。

• 執行簡單的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>

建立Swagger2配置類

在HrabbitAdminApplication.java子包下建立Swagger2的配置類Swagger2。
透過@Configuration註解，讓Spring來載入該類配置。再透過@EnableSwagger2註解來啟用Swagger2。
再透過createRestApi函式建立Docket的Bean之後，apiInfo()用來建立該Api的基本資訊（這些基本資訊會展現在文件頁面中）。select()函式返回一個ApiSelectorBuilder例項用來控制哪些介面暴露給Swagger來展現，包含註解的方式來確定要顯示的介面，當然也可以透過包掃描的方式來確定要顯示的包的介面。

/**
 * 配置Swagger
 *
 * @Auther: hrabbit
 * @Date: 2018-12-17 6:43 PM
 * @Description:
 */@Configuration@EnableSwagger2public 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("")
                .contact("hrabbit")
                .version("1.0")
                .build();
    }

}

新增文件內容

我們透過@Api說明Controller，@ApiOperation註解來給API增加說明、透過@ApiImplicitParams、@ApiImplicitParam註解來給引數增加說明。

/**
 * 系統使用者
 *
 * @Auther: hrabbit
 * @Date: 2018-12-17 6:21 PM
 * @Description:
 */@Controller@RequestMapping("user")@Api(value = "系統使用者")public class SysUserController {    @Autowired
    private SysUserService sysUserService;    /**
     * 根據id獲取使用者資訊
     *
     * @return
     */
    @RequestMapping("/",method = RequestMethod.GET)    @ResponseBody
    @ApiOperation(value = "進入到主頁")    public Object index() {        return sysUserService.selectById(1L);
    }    /**
     * 建立使用者資訊
     *
     * @param user
     * @return
     */
    @ApiOperation(value = "建立使用者", notes = "根據SysUser物件建立使用者")    @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 = "根據id更新系統使用者")    @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程式，訪問：
。就能看到前文所展示的RESTful API的頁面。我們可以再點開具體的API請求，以POST型別的/user請求為例，可找到上述程式碼中我們配置的Notes資訊以及引數user的描述資訊，如下圖所示。

image.png

API文件訪問與除錯

在上圖請求的頁面中，我們看到user的Value是個輸入框？是的，Swagger除了檢視介面功能外，還提供了除錯測試功能，我們可以點選上圖中右側的Model Schema（黃色區域：它指明瞭User的資料結構），此時Value中就有了user物件的模板，我們只需要稍適修改，點選下方“Try it out！”按鈕，即可完成了一次請求呼叫！

本篇文章，一些文字內容借鑑了程式猿DD的Swagger內容，該系列文章內容主要以如何搭建一個完整的後臺Spirng Boot Cli為主，其他的基礎資訊可以參考其他博主內容！

碼雲地址：

作者：hrabbits
連結：