接口文檔是一個軟件系統的重要組成部分，它描述了系統中所有可供外部應用程序使用的接口。簡單來說，接口文檔就是用來幫助開發者開發和對接系統的指南。在軟件開發過程中，不同的系統之間需要進行數據交互和信息傳遞，這就要求系統必須提供一些公開的接口。

大家好！我是sum墨，一個一線的底層碼農，平時喜歡研究和思考一些技術相關的問題并整理成文，限于本人水平，如果文章和代碼有表述不當之處，還請不吝賜教。

以下是正文！

接口文檔是什么

接口文檔是一個軟件系統的重要組成部分，它描述了系統中所有可供外部應用程序使用的接口。簡單來說，接口文檔就是用來幫助開發者開發和對接系統的指南。

在軟件開發過程中，不同的系統之間需要進行數據交互和信息傳遞，這就要求系統必須提供一些公開的接口。

接口文檔的展現形式也很多如：Swagger、Word、PDF、Postman、開放平臺文檔等。不同的展現形式提供了不同的載體來呈現接口文檔，但是最終的關鍵還是內容本身。

一份清晰、詳細、準確的接口文檔是開發團隊是否能夠準確理解和使用系統接口的關鍵。

總之，一份好的接口文檔應該覆蓋所有的接口使用場景，詳盡而不冗長，方便開發者快速查找和使用。而對于不同的展現形式，開發者需要根據項目的需求和開發流程選擇最適合的展現方式，從而提高開發效率和工作質量。

Swagger接口文檔

Swagger是一套用于設計、構建、記錄和使用RESTful API的工具集，可以自動生成API文檔，并提供交互式UI，能夠大大提高開發效率和協作效率。它支持多種編程語言和框架，能夠生成多種展現形式，如Swagger UI、Swagger Editor和Swagger Codegen等工具。同時，Swagger還提供強大的API管理功能，包括API監控、調試、測試和安全性等，能夠幫助開發者更好地管理和維護API。

展示一下

訪問方式一

訪問地址：http://localhost:8080/swagger-ui.html#/

首頁

詳情頁

訪問方式二

訪問地址：http://localhost:8080/doc.html

首頁

側邊欄

詳情頁

SpringBoot整合Swagger2

1、配置文件

SpringBoot項目pom.xml

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>2.2.6.RELEASE</version>
        <relativePath/> <!-- lookup parent from repository -->
    </parent>
    <groupId>com.example</groupId>
    <artifactId>springboot-swagger</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>springboot-swagger</name>
    <description>Demo project for Spring Boot</description>
    <properties>
        <java.version>1.8</java.version>
    </properties>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>

        <!-- swagger -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.2</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>

</project>

這里需要注意一個版本對應的問題，如果使用了高版本的SpringBoot框架，低版本的Swagger，
會出現如下報錯：

org.springframework.context.ApplicationContextException: Failed to start bean 'documentationPluginsBootstrapper'; nested exception is java.lang.NullPointerException
	at org.springframework.context.support.DefaultLifecycleProcessor.doStart(DefaultLifecycleProcessor.java:181)
	at org.springframework.context.support.DefaultLifecycleProcessor.access$200(DefaultLifecycleProcessor.java:54)
	at org.springframework.context.support.DefaultLifecycleProcessor$LifecycleGroup.start(DefaultLifecycleProcessor.java:356)
	at java.lang.Iterable.forEach(Iterable.java:75)
	at org.springframework.context.support.DefaultLifecycleProcessor.startBeans(DefaultLifecycleProcessor.java:155)
	at org.springframework.context.support.DefaultLifecycleProcessor.onRefresh(DefaultLifecycleProcessor.java:123)
	at org.springframework.context.support.AbstractApplicationContext.finishRefresh(AbstractApplicationContext.java:935)
	at org.springframework.context.support.AbstractApplicationContext.refresh(AbstractApplicationContext.java:586)
	at org.springframework.boot.web.servlet.context.ServletWebServerApplicationContext.refresh(ServletWebServerApplicationContext.java:145)
	at org.springframework.boot.SpringApplication.refresh(SpringApplication.java:740)
	at org.springframework.boot.SpringApplication.refreshContext(SpringApplication.java:415)
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:303)
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:1312)
	at org.springframework.boot.SpringApplication.run(SpringApplication.java:1301)

這是因為：因為Springfox 使用的路徑匹配是基于AntPathMatcher的，而Spring Boot 2.6.X使用的是PathPatternMatcher。

以下幾個版本是兼容的

SpringBoot版本	Swagger版本
2.5.6	2.9.2

SpringBoot版本	Swagger版本
2.6.5	3.0.0

2、項目代碼

項目結構

SwaggerConfig.java

package com.example.springbootswagger.config;

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.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;

@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createDocket() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(true)
                .groupName("我的接口文檔")
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.springbootswagger.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //標題
                .title("鳳求凰")
                //作者、鏈接、郵箱等
                .contact(new Contact(
                        "司馬相如",
                        "https://hanyu.baidu.com/shici/detail?pid=ecb82707a98c418995c5a0c50b770af0&from=kg0",
                        ""
                ))
                //描述
                .description("有一美人兮，見之不忘。\n" +
                        "一日不見兮，思之如狂。\n" +
                        "鳳飛翱翔兮，四海求凰。\n" +
                        "無奈佳人兮，不在東墻。\n" +
                        "將琴代語兮，聊寫衷腸。\n" +
                        "何日見許兮，慰我彷徨。\n" +
                        "愿言配德兮，攜手相將。\n" +
                        "不得於飛兮，使我淪亡。\n" +
                        "鳳兮鳳兮歸故鄉，遨游四海求其凰。\n" +
                        "時未遇兮無所將，何悟今兮升斯堂！\n" +
                        "有艷淑女在閨房，室邇人遐毒我腸。\n" +
                        "何緣交頸為鴛鴦，胡頡頏兮共翱翔！\n" +
                        "凰兮凰兮從我棲，得托孳尾永為妃。\n" +
                        "交情通意心和諧，中夜相從知者誰？\n" +
                        "雙翼俱起翻高飛，無感我思使余悲。")
                //更新說明
                .termsOfServiceUrl("這是第一版")
                //版本號
                .version("1.0.0").build();
    }
}

TestController.java

package com.example.springbootswagger.controller;

import com.example.springbootswagger.req.AddReq;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

@RestController
@Api(tags = {"測試接口類"}, hidden = true)
@RequestMapping("/test")
public class TestController {

    @ApiOperation("GET請求，查詢方法")
    @GetMapping("/query")
    public String query() {
        return "查詢成功";
    }

    @ApiImplicitParams({
            @ApiImplicitParam(name = "param1", value = "參數1", required = true),
            @ApiImplicitParam(name = "param2", value = "參數2", required = false)
    })
    @ApiOperation("PUT請求，添加方法")
    @PutMapping("/update")
    public String update(
            @RequestParam(required = true) String param1,
            @RequestParam(required = false) String param2) {
        return "更新成功";
    }

    @ApiOperation("POST請求，修改方法")
    @PostMapping("/add")
    public String add(@RequestBody AddReq addReq) {
        return "添加成功";
    }

    @ApiImplicitParam(name = "id", value = "用戶ID", required = true)
    @ApiOperation("DELETE請求，刪除方法")
    @DeleteMapping("/del")
    public String del(Long id) {
        return "刪除成功";
    }
}

AddReq.java

package com.example.springbootswagger.req;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

@ApiModel("添加參數")
public class AddReq {

    @ApiModelProperty("名字")
    private String name;

    @ApiModelProperty("密碼")
    private String password;

    public String getName() {
        return name;
    }

    public void setName(String name) {
        this.name = name;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }
}

SpringbootSwaggerApplication.java

package com.example.springbootswagger;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@EnableSwagger2
@SpringBootApplication
public class SpringbootSwaggerApplication {

    public static void main(String[] args) {
        SpringApplication.run(SpringbootSwaggerApplication.class, args);
    }

}

Word、PDF等文件類接口文檔

為什么還需要文件類接口文檔呢？首先，Swagger文檔存在兼容性問題，有些系統不支持，這時候文件類接口文檔就能派上用場。其次，Swagger文檔不能離線使用，如果網絡不穩定或者沒有網絡連接，就無法查看接口文檔，而文件類接口文檔可以在任何時候離線瀏覽。

之前我有寫過一篇關于系統間交互的文章:多方合作時，系統間的交互是怎么做的？，系統間的接口交互一般提供的都是文件類文檔，像Word、PDF這種。

在實際開發中，我發現不同的開發團隊提供的接口文檔格式存在很大的差異。有些團隊提供的文檔非常詳細，甚至會給出調用示例代碼，而有些團隊則只提供了非常簡單的接口說明，甚至連參數說明都沒有。這種情況下，如果接口文檔很詳細，我可以很快地進行調試和聯調，但是如果文檔不夠詳細，很容易遇到各種坑（一言難盡的坑），必須要去找對方的開發。

我覺得一份好的接口文檔應該包括以下內容：

• 接口概述：包括接口的名稱、描述、版本號等信息，讓開發者了解接口的基本信息。

• 接口參數：包括請求參數和返回參數，需要詳細說明每個參數的名稱、類型、描述、默認值、是否必須等信息，讓開發者清晰地知道每個參數的含義和使用方法。

• 接口使用示例：提供一個或多個請求和相應的示例，讓開發者更好地理解接口的使用方法和返回結果。

• 接口錯誤碼：列出所有可能出現的錯誤碼和相應的錯誤信息，讓開發者了解如何識別和處理接口返回的錯誤。

• 接口限制和安全性：包括接口的訪問限制、頻次限制、安全性等信息，讓開發者知道如何正確地使用接口。

以下是我認為樣式較為簡潔和清晰的 Word 模板接口文檔示例（最下方是模板下載鏈接）：

模板下載鏈接