Spring Boot集成Swagger

• Spring Boot集成Swagger
  • 前言
  • 基本概述
  • 案例
    • 引入依賴
    • Swagger配置
    • 配置方式
      • 基本概述
      • 控制器
      • 統一回應類
      • 用戶Model
      • 檔案界面
  • 原始碼
  • 參考資訊

前言

為了完成專案自帶檔案的需求，花了一定的時間研究Spring Boot集成Swagger，看了官方檔案和一些博客，差不多搭出一個比較通用的架子，

文末會分享出案例專案，

基本概述

本文使用Spring Boot+Spring Fox的方式集成Swagger框架，

案例

引入依賴

<properties>
    <swagger.version>2.7.0</swagger.version>
</properties>
<dependencies>
    <!-- swagger2 -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger2</artifactId>
        <version>${swagger.version}</version>
    </dependency>
    <!-- swagger2 ui -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>${swagger.version}</version>
    </dependency>
</dependencies>

Swagger配置

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.switchvov.swagger"))
                .paths(PathSelectors.any())
                .build()
                .securitySchemes(securitySchemes())
                .securityContexts(securityContexts());
    }

    /**
     * 配置認證模式
     */
    private List<ApiKey> securitySchemes() {
        return newArrayList(new ApiKey("Authorization", "Authorization", "header"));
    }

    /**
     * 配置認證背景關系
     */
    private List<SecurityContext> securityContexts() {
        return newArrayList(SecurityContext.builder()
                .securityReferences(defaultAuth())
                .forPaths(PathSelectors.any())
                .build());
    }

    private List<SecurityReference> defaultAuth() {
        AuthorizationScope authorizationScope = new AuthorizationScope("global", "accessEverything");
        AuthorizationScope[] authorizationScopes = new AuthorizationScope[1];
        authorizationScopes[0] = authorizationScope;
        return newArrayList(new SecurityReference("Authorization", authorizationScopes));
    }

    /**
     * 專案資訊
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Swagger測驗專案 RESTful APIs")
                .version("1.0")
                .build();
    }
}

配置方式

基本概述

Swagger官方Wiki 注解
swagger2常用注解說明
swagger注釋API詳細說明

PS：以上幾篇文章已經將Swagger注解的使用方式及作用闡述的非常清楚了，這里只給出代碼案例，

PS：springfox-swagger2:2.7.0已經支持泛型回傳物件，
注意：千萬不要在@ApiOperation注解里限定response()，讓框架推斷型別就行了，

控制器

@RestController
@RequestMapping(value = "https://www.cnblogs.com/user", produces = "application/json")
@Api(value = "https://www.cnblogs.com/switchvov/p/User", tags = {"User"}, description = "用戶相關")
public class UserController {
    @Autowired
    private UserService userService;

    @GetMapping("/{id}")
    @ApiOperation(value = "https://www.cnblogs.com/switchvov/p/使用ID查詢用戶")
    @ApiImplicitParams({
            @ApiImplicitParam(value = "https://www.cnblogs.com/switchvov/p/ID", name = "id", dataType = "int", paramType = "path", required = true, defaultValue = "https://www.cnblogs.com/switchvov/p/1")
    })
    @ApiResponses({
            @ApiResponse(code = 400, message = "請求引數有誤"),
            @ApiResponse(code = 401, message = "未授權"),
            @ApiResponse(code = 403, message = "禁止訪問"),
            @ApiResponse(code = 404, message = "請求路徑不存在"),
            @ApiResponse(code = 500, message = "服務器內部錯誤")
    })
    public ResponseResult<User> getById(@PathVariable("id") Integer id) {
        User user = userService.getById(id);
        return ResponseResult.successWithData(user);
    }

    @PostMapping("")
    @ApiOperation(value = "https://www.cnblogs.com/switchvov/p/創建用戶")
    @ApiResponses({
            @ApiResponse(code = 400, message = "請求引數有誤"),
            @ApiResponse(code = 401, message = "未授權"),
            @ApiResponse(code = 403, message = "禁止訪問"),
            @ApiResponse(code = 404, message = "請求路徑不存在"),
            @ApiResponse(code = 500, message = "服務器內部錯誤")
    })
    public ResponseResult<User> createUser(@Validated @RequestBody User user) {
        User dbUser = userService.createUser(user);
        return ResponseResult.successWithData(dbUser);
    }
}

統一回應類

@ApiModel(description = "回應物件")
public class ResponseResult<T> {
    private static final int SUCCESS_CODE = 0;
    private static final String SUCCESS_MESSAGE = "成功";

    @ApiModelProperty(value = "https://www.cnblogs.com/switchvov/p/回應碼", name = "code", required = true, example = "" + SUCCESS_CODE)
    private int code;

    @ApiModelProperty(value = "https://www.cnblogs.com/switchvov/p/回應訊息", name = "msg", required = true, example = SUCCESS_MESSAGE)
    private String msg;

    @ApiModelProperty(value = "https://www.cnblogs.com/switchvov/p/回應資料", name = "data")
    private T data;

	// 省略get、set方法等等，詳見源代碼
}

用戶Model

PS：用戶model使用了lombok、jpa、validator，只需要關注@Api開頭的注解就行了，

@Data
@Entity(name = "users")
@ApiModel(description = "用戶Model")
public class User {
    @Id
    @GeneratedValue(strategy = GenerationType.AUTO)
    @Null(message = "id必須為空")
    @ApiModelProperty(value = "https://www.cnblogs.com/switchvov/p/用戶ID", name = "id")
    private Integer id;

    @Column
    @NotBlank(message = "用戶名不能為空")
    @ApiModelProperty(value = "https://www.cnblogs.com/switchvov/p/用戶名", name = "username", required = true, example = "zhaoliu")
    private String username;

    @Column
    @NotBlank(message = "密碼不能為空")
    @ApiModelProperty(value = "https://www.cnblogs.com/switchvov/p/密碼", name = "password", required = true, example = "123456")
    private String password;
}

檔案界面

原始碼

GitHub：swagger-demo

參考資訊

• SpringFox官網
• Swagger官方Wiki 注解
• Spring Boot中使用Swagger2構建強大的RESTful API檔案
• 第四章 springboot + swagger
• Spring啟動RESTful API檔案使用Swagger 2
• swagger2常用注解說明
• swagger注釋API詳細說明
• Swagger2 添加HTTP head引數
• Swagger2 非全域、無需重復輸入的Head引數（Token）配置

分享并記錄所學所見

標籤：Java

上一篇：【JavaSE】泛型知識點（總結）

下一篇：JPA、Hibernate、Spring Data JPA 的關系，你懂嗎？