springboot 集成Swagger2

一、Swagger簡介

Swagger 是最流行的 API 開發工具，它遵循 OpenAPI Specification（OpenAPI 規範，也簡稱 OAS）。
Swagger 可以貫穿於整個 API 生態，如 API 的設計、編寫 API 文檔、測試和部署。
Swagger 是一種通用的，和編程語言無關的 API 描述規範。

 

二、應用場景

• 如果你的 RESTful API 接口都開發完成了，你可以用 Swagger-editor 來編寫 API 文檔（ yaml 文件 或 json 文件），然後通過 Swagger-ui 來渲染該文件，以非常美觀的形式將你的 API 文檔，展現給你的團隊或者客戶。
• 如果你的 RESTful API 還未開始，也可以使用 Swagger ，來設計和規範你的 API，以 Annotation （註解）的方式給你的源代碼添加額外的數據。這樣，Swagger 就可以檢測到這些數據，自動生成對應的 API 文檔。

 

三、Swagger工具

Swagger提供了多種工具，幫助解決api的不同的情況下的問題

Swagger-ui 是一套 HTML/CSS/JS 框架，用於渲染 Swagger 文檔，以便提供美觀的 API 文檔界面。也就是說，Swagger-ui 是一個 UI 渲染工具。

 

三、集成步驟

1、配置Maven依賴

<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger2</artifactId>
  <version>2.9.2</version>
</dependency>
<dependency>
  <groupId>io.springfox</groupId>
  <artifactId>springfox-swagger-ui</artifactId>
  <version>2.9.2</version>
</dependency>

 

2、Swagger配置類

/**
 * Copyright (c) 2016-2019 人人開源 All rights reserved.
 *
 * https://www.renren.io
 *
 * 版權所有，侵權必究！
 */

package com.example.demo.config;


import io.swagger.annotations.ApiOperation;
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.ApiKey;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.List;

import static com.google.common.collect.Lists.newArrayList;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            //加了ApiOperation註解的類，才生成接口文檔
            .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
            //包下的類，才生成接口文檔
            //.apis(RequestHandlerSelectors.basePackage("io.renren.controller"))
            .paths(PathSelectors.any())
            .build()
            .securitySchemes(security());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("人人開源")
            .description("renren-api文檔")
            .termsOfServiceUrl("https://www.renren.io")
            .version("4.0.0")
            .build();
    }

    private List<ApiKey> security() {
        return newArrayList(
            new ApiKey("token", "token", "header")
        );
    }

}

 

3、在Controller中使用Swagger註解

@RestController
@Api(tags="用戶管理")
public class UserController {

    @GetMapping("/user/list")
    @ApiOperation("列表")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "username", value = "用戶名", paramType = "query", required = true, dataType="string"),
             @ApiImplicitParam(name = "password", value = "密碼", paramType = "query",required = true, dataType="string")
            })
    public String list(String username,String password)
    {
        System.out.println(username);
        System.out.println(password);
        return "success";
    }
}

註解說明

• @Api：用在類上，說明該類的作用。
• @ApiOperation：註解來給API增加方法說明。
• @ApiImplicitParams : 用在方法上包含一組參數說明。
• @ApiImplicitParam：用來註解來給方法入參增加說明。
• @ApiResponses：用於表示一組響應
• @ApiResponse：用在@ApiResponses中，一般用於表達一個錯誤的響應信息
• @ApiModel：描述一個Model的信息（一般用在請求參數無法使用@ApiImplicitParam註解進行描述的時候）
• @ApiModelProperty：描述一個model的屬性

 

4、輸入網址localhost:8080/swagger-ui.html，測試api