本文轉(zhuǎn)載自微信公眾號(hào)「Java技術(shù)指北」，作者指北君 。轉(zhuǎn)載本文請(qǐng)聯(lián)系Java技術(shù)指北公眾號(hào)。

大家好， 我是指北君。

相信大家平時(shí)開(kāi)發(fā)的過(guò)程中，都會(huì)使用到 API文檔工具吧?大家都在使用什么呀?Java docs，I/O Docs, apiary.io, Docco, Dexy, Doxygen, TurnAPI，Swagger。今天我就來(lái)教大家如何使用 Swagger 搭建 API 文檔，并且配置權(quán)限使用。畢竟開(kāi)發(fā)文檔還是內(nèi)容使用的為好，萬(wàn)一上線到生產(chǎn)環(huán)境，沒(méi)有關(guān)swagger 又沒(méi)有設(shè)置權(quán)限，那可不GG啦。

好，我們這就上手搞起來(lái)。

我們將使用 Springfox 對(duì) Swagger 2 規(guī)范的實(shí)現(xiàn)，并通過(guò) JWT 的方式來(lái)設(shè)置權(quán)限。

配置SwaggerUI

第一步：向Spring Boot項(xiàng)目添加Maven依賴項(xiàng)

打開(kāi) pom.xml 文件，添加 springfox-boot-starter 到 maven 依賴中。

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-boot-starter</artifactId>
    <version>3.0.0</version>
</dependency>

添加 springfox-boot-starter 依賴后，spring boot 能啟動(dòng)配置功能，配置好 swagger，所以我們不需要手動(dòng)添加注解來(lái)啟用 Swagger。

我們啟動(dòng)一下項(xiàng)目訪問(wèn) Swagger 文檔的 JSON API , 來(lái)看看 Springfox 是否正常運(yùn)行。我們可以在瀏覽器中輸入以下URL：

http://localhost:8080/v3/api-docs

能夠看到以上的類似結(jié)果，說(shuō)明我們第一步已經(jīng)成功了。

第二步：將 Swagger 2 集成到 Spring Boot項(xiàng)目中去

我們創(chuàng)建一個(gè) SwaggerConfig 類，并用 @Configuration 注解來(lái)注釋。Swagger 的配置主要圍繞著 Docket 對(duì)象來(lái)完成。我們可以在 SwaggerConfig 類中添加以下代碼。

@Configuration
public class SwaggerConfiguration {
    private ApiInfo apiInfo() {
        return new ApiInfo("Blog REST APIs",
                "REST APIs for Blog Application",
                "1.0",
                "Terms of service",
                new Contact("xxx", "xxx", "xxx"),
                "License of API",
                "API license URL",
                Collections.emptyList());
    }
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
}

在構(gòu)造 Docket 對(duì)象之后，它的 select() 方法返回了 ApiSelectorBuilder 的一個(gè)實(shí)例，它提供了一種控制 Swagger 所暴露的端點(diǎn)的方法。

我們可以通過(guò)使用 RequestHandlerSelectors 和 PathSelectors 配置選擇 RequestHandlers 的路徑。如果兩者兩者使用 any() ， 那就說(shuō)明配置所有的 API 都能在 Swagger 上顯示了。

第三步：訪問(wèn) Swagger UI

Swagger UI 是一個(gè)內(nèi)置的解決方案，使用戶與Swagger 生成的API文檔的交互變得更加容易。我們?cè)跒g覽器中輸入下面URL即可查看：

http://localhost:8080/swagger-ui/

結(jié)果應(yīng)該是這樣的。

好，到這里 Swagger 的使用配置就算結(jié)束了。那接下來(lái)我們來(lái)看看怎么用JWT增加權(quán)限配置呢?

配置 JWT

JWT 是什么?相信大家都一定聽(tīng)過(guò)吧，它就是 JSON Web Token 的縮寫。話不多說(shuō)，直接上手代碼配置起來(lái)。在 SwaggerConfig 里面新增代碼。

我們先來(lái)配置 ApiKey 作為 JWT 的認(rèn)證 header信息：

   public static final String AUTHORIZATION_HEADER = "Authorization";
    private ApiKey apiKey(){
        return new ApiKey("JWT", AUTHORIZATION_HEADER, "header");
    }

下一步，我們配置 JWT 的 SecurityContext ， 對(duì) SecurityContext 配置全局的 AuthorizationScope :

   private SecurityContext securityContext(){
        return SecurityContext.builder().securityReferences(defaultAuth()).build();
    }
    private List<SecurityReference> defaultAuth(){
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        return Arrays.asList(new SecurityReference("JWT", authorizationScopes));
    }

然后我們配置 Docket 對(duì)象，對(duì) Docket 對(duì)象設(shè)置 SecurityContext ，SecuritySchemes。

   @Bean
    public Docket api(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .securityContexts(Arrays.asList(securityContext()))
                .securitySchemes(Arrays.asList(apiKey()))
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }

到這里，JWT 就配置完成了，感覺(jué)是不是挺簡(jiǎn)單的?好，我們?cè)賮?lái)運(yùn)行一下，看看效果

我們點(diǎn)擊右上角的 Authorize 按鈕，彈出一個(gè)輸入 apiKey 的彈出層。

輸入 api key 之后，點(diǎn)擊 Authorize 認(rèn)證通過(guò)，我們就又能調(diào)用 API 接口調(diào)試了。

用注解定制 Swagger API 文檔

為了能夠定制 Swagger 文檔，swagger-core 提供了一套注解來(lái)聲明和操作輸出。

Swagger-core 注解:

更多詳細(xì)的說(shuō)明可以參考 GitHub 上的解釋：https://github.com/swagger-api/swagger-core/wiki/annotations

現(xiàn)在我們就舉個(gè)例子來(lái)解釋怎么使用這些個(gè)注解， 首先來(lái)看 @Api 和 @ApiOperation 怎么使用：

@Api(value = "CRUD Rest APIs for Post resources")
@RestController
@RequestMapping()
public class PostController {
    @ApiOperation(value = "Get All Posts REST API")
    @GetMapping("/api/v1/posts")
    public PostResponse getAllPosts(
            @RequestParam(value = "pageNo", defaultValue = "0", required = false) int pageNo,
            @RequestParam(value = "pageSize", defaultValue = "100", required = false) int pageSize
    ){
        ...
    }
 
}

再來(lái)看看 @ApiModel 和 @ApiModelProperty 怎么使用：

@ApiModel(description = "Post model information")
@Data
public class PostDto {
    @ApiModelProperty(value = "Blog post id")
    private long id;
}

是不是感覺(jué) so easy?

總結(jié)

通過(guò)這篇文章我們學(xué)習(xí)了如何通過(guò) Springfox 來(lái)搭建 Swagger API 文檔平臺(tái)，然后也學(xué)會(huì)了如何設(shè)置 JWT 的方式做認(rèn)證，保證 API 不會(huì)被別人能夠惡意使用。