【掌握Swagger 2.0】從入門到精通，API文檔編寫實戰指南

最佳答案

引言

在當今的軟體開辟範疇，API（利用順序編程介面）已成為構建分散式體系跟微效勞架構的核心。Swagger 2.0 是一個富強的東西，它可能幫助開辟者輕鬆地創建、保護跟可視化 RESTful API 文檔。本文將帶你從入門到粗通，深刻懂得 Swagger 2.0 的利用，並經由過程實戰示例展示怎樣編寫高品質的 API 文檔。

一、Swagger 2.0 簡介

Swagger 2.0 是一個開源項目，它遵守 OpenAPI 標準，用於計劃、構建跟文檔化 RESTful API。它供給了以下核心功能：

主動生成 API 文檔：根據代碼注釋跟設置主動生成 API 文檔。
互動式 API 測試：供給互動式界面，容許開辟者測試跟調試 API 介面。
API 計劃跟合作：支撐 API 計劃跟團隊合作。

二、集成 Swagger 2.0

1. 增加依附

以 Spring Boot 項目為例，你須要在 pom.xml 文件中增加以下依附：

<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

創建一個設置類，用於啟用 Swagger 2.0：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType.SWAGGER_2)
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
}

3. 拜訪 Swagger UI

啟動 Spring Boot 利用順序後，拜訪 http://localhost:8080/swagger-ui.html，你將看到 Swagger UI 界面，可能在這裡檢查跟測試 API 文檔。

三、編寫 API 文檔

1. 利用註解

Swagger 供給了一系列註解，用於定義 API 的各種細節。以下是一些常用的註解：

@Api：用於定義 API 的基本信息。
@ApiOperation：用於定義 API 的操縱信息。
@ApiParam：用於定義 API 的參數信息。
@ApiResponse：用於定義 API 的呼應信息。

2. 實戰示例

以下是一個利用 Swagger 註解的示例：

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiParam;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
@Api(value = "示例 API")
public class ExampleController {

    @ApiOperation(value = "獲取用戶信息")
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "成功"),
            @ApiResponse(code = 404, message = "用戶不存在")
    })
    @GetMapping("/user")
    public String getUser(@ApiParam(value = "用戶 ID", required = true) @RequestParam Long userId) {
        // 獲取用戶信息
        return "用戶信息";
    }
}

四、總結

Swagger 2.0 是一個富強的東西，可能幫助開辟者輕鬆地創建、保護跟可視化 RESTful API 文檔。經由過程本文的介紹，你應當曾經控制了 Swagger 2.0 的基本利用方法。在現實項目中，你可能根據須要調劑設置跟註解，以生成符合請求的 API 文檔。