接口文档模板与 .NET 平台应用场景

Tue, 15 May 2018 00:00:00 +0800

前置知识

至少调用过一个 HTTP API（GET / POST / JSON）
知道什么是 REST、什么是接口
了解任一后端语言（Java / Go / Python 即可）

一份合格的接口文档应该长什么样

2010 年代中后期，微服务、API 经济、OpenAPI 规范逐步走向主流——前后端分离的协作模式倒逼后端必须给前端 / 移动端 / 第三方提供"机器可读 + 人可读"两份接口契约。

一份合格的接口文档必须回答 5W1H：

维度	回答什么
What	接口是什么？功能描述
Where	接口在哪？URL / IP / 端口
When	何时调用？超时、重试、限流
Who	谁可以调？鉴权方式
Which	进出什么数据？字段含义、类型、必填
How	怎么调？HTTP 方法、Headers、错误码

下面是一份可直接复用的 Markdown 模板。

一、接口文档 Markdown 模板

1.1 顶层信息

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 接口名

## 接口协议：http / https

## 接口地址：写明需要调用的地址或 IP

## 接口端口：服务开启的端口号

## 目录（自动生成）

[TOC]

1.2 单接口详细说明

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45


## 1. 简单描述接口

### 接口功能

> 描述这个接口是干什么用的，基本逻辑是什么

### URL

> 接口调用地址，例：`/api/rest/wasteMap/entInfo/getEntInfoById`

### 支持格式

> `json` / `html` / `xml`

### HTTP 请求方式

> `GET` / `POST` / `PUT` / `DELETE`

### 请求参数

| 参数 | 必选 | 类型 | 说明 |
| :--- | :--- | :--- | :--- |
| id | 是 | string | 实体唯一标识 |
| name | 否 | string | 名称（模糊匹配） |

### 返回字段

| 返回字段 | 字段类型 | 说明 |
| :--- | :--- | :--- |
| code | int | 状态码，200=成功 |
| msg | string | 提示信息 |
| data | object | 业务数据 |
| data.id | string | 实体 ID |
| data.name | string | 实体名称 |

### 接口示例

> 调用地址：`http://api.example.com:8080/api/rest/...`

#### 请求参数

```json
{
 "id": "10001"
}

返回结果

1
2
3
4
5
6
7
8


{
 "code": 200,
 "msg": "成功",
 "data": {
 "id": "10001",
 "name": "示例"
 }
}

错误码

错误码	含义	处理建议
200	成功	-
400	参数错误	检查请求参数
401	未授权	重新登录获取 token
403	无权限	联系管理员
404	资源不存在	检查 id
500	服务器异常	联系后端

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53



### 1.3 完整示例

```markdown
# 危险废物地图 - 企业详情查询

## 接口协议：https

## 接口地址：api.example.com

## 接口端口：443

## 1. 简单描述接口

### 接口功能

> 根据企业 ID 查询企业基本信息、许可证信息、危废产生量

### URL

> `/api/rest/wasteMap/entInfo/getEntInfoById`

### 支持格式

> json

### HTTP 请求方式

> GET

### 请求参数

| 参数 | 必选 | 类型 | 说明 |
| :--- | :--- | :--- | :--- |
| entId | 是 | string | 企业 ID |

### 返回字段

| 返回字段 | 字段类型 | 说明 |
| :--- | :--- | :--- |
| code | int | 状态码 |
| msg | string | 描述 |
| data | object | 企业信息 |
| data.entName | string | 企业名称 |
| data.legalPerson | string | 法人 |
| data.address | string | 地址 |
| data.licenses | array | 许可证列表 |

### 接口示例

> 地址：`https://api.example.com/api/rest/wasteMap/entInfo/getEntInfoById?entId=10001`

#### 请求 Headers

Authorization: Bearer eyJhbGciOiJIUzI1NiJ9… Content-Type: application/json

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19



#### 返回结果

```json
{
 "code": 200,
 "msg": "成功",
 "data": {
 "entName": "某环保科技公司",
 "legalPerson": "张三",
 "address": "江苏省南京市江宁区...",
 "licenses": [
 {
 "licNo": "HW-2024-001",
 "validUntil": "2027-12-31"
 }
 ]
 }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42



## 二、接口文档工具链

### 2.1 OpenAPI 3.0（Swagger）

2015 年 Swagger 规范被 SmartBear 捐给 Linux 基金会，演化为 **OpenAPI 3.0**——机器可读的接口定义标准。

```yaml
# openapi.yaml
openapi: 3.0.0
info:
 title: 示例 API
 version: 1.0.0
 description: 危险废物地图服务
servers:
 - url: https://api.example.com
paths:
 /api/rest/wasteMap/entInfo/getEntInfoById:
 get:
 summary: 查询企业详情
 parameters:
 - name: entId
 in: query
 required: true
 schema:
 type: string
 responses:
 '200':
 description: 成功
 content:
 application/json:
 schema:
 $ref: '#/components/schemas/EntInfo'
components:
 schemas:
 EntInfo:
 type: object
 properties:
 entName:
 type: string
 legalPerson:
 type: string

工具链：

Swagger UI：把 YAML 渲染成可调试的网页（/swagger-ui/index.html）
Swagger Editor：在线编辑器
Swagger Codegen：自动生成 Java / Go / TS 客户端 SDK
Springdoc / springfox：Java 注解自动生成 OpenAPI YAML

2.2 API 文档平台

工具	优势	适合
Swagger / OpenAPI	行业标准	任何规模
Postman	协作 + 调试	前后端协作
Apifox	国产、UI 友好	中小团队
ShowDoc	国产、轻量	内部文档
语雀 / 飞书	知识库	业务文档为主
ReadMe	商业化、交互式	SaaS 产品

2.3 文档即代码（Doc-as-Code）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# Git 仓库结构
docs/
├── api/
│ ├── openapi.yaml # 接口定义
│ ├── errors.md # 错误码字典
│ └── auth.md # 鉴权说明
├── guides/
│ ├── quickstart.md
│ └── best-practices.md
└── README.md

版本随代码走（PR review 改接口必改文档）
CI 自动部署到内网 / 公网（GitHub Pages + 自动构建）
评审流程与代码一致

三、.NET 平台应用场景

3.1 .NET Framework vs .NET Core

维度	.NET Framework	.NET Core / .NET 5+
平台	Windows only	跨平台（Win / macOS / Linux）
开源	闭源	MIT 开源（2014 年起）
性能	一般	比 Framework 快 2-10 倍
微服务	不友好	一等公民
容器化	难	镜像 100MB-
现状	维护模式	主流

2016 年微软开源 .NET Core 1.0、2017 年发布 2.0、2020 年 .NET 5 统一品牌、2024 年 .NET 9 已是事实标准。

3.2 七大应用领域

① Web 应用

ASP.NET Core MVC / Razor Pages / Blazor：

1
2
3
4
5
6
7
8
9


// Razor Page
@page
@model IndexModel
@{
 ViewData["Title"] = "首页";
}

<h1>@Model.Greeting</h1>
<p>当前时间：@DateTime.Now</p>

适合：企业内网系统、SaaS 后台、CMS。

② 移动开发

Xamarin（2011 年起）+ .NET MAUI（2022 年起）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


// .NET MAUI
public partial class MainPage : ContentPage
{
 public MainPage()
 {
 InitializeComponent();
 }

 void OnCounterClicked(object sender, EventArgs e)
 {
 count++;
 CounterLabel.Text = $"点击 {count} 次";
 }
}

一份 C# 代码，编译成 iOS / Android / Windows / macOS 原生应用。

③ 桌面应用程序

WPF（Windows Presentation Foundation）——Windows 桌面 UI
WinForms —— 老式 Windows 桌面
WinUI 3 —— 现代 Windows 11 风格
Avalonia —— 跨平台桌面 UI（类似 Flutter 思路）

适合：企业内部工具、IDE 插件、客户端软件。

④ 微服务与容器

ASP.NET Core + Docker + Kubernetes：

1
2
3
4
5


# 5MB 镜像级别
FROM mcr.microsoft.com/dotnet/aspnet:9.0-alpine
WORKDIR /app
COPY --from=build /app/publish .
ENTRYPOINT ["dotnet", "MyService.dll"]

.NET 9 + NativeAOT（Ahead-of-Time）编译后镜像 50MB，启动 < 100ms——对标 Go 的部署体验。

⑤ 云应用程序

Azure 一等公民，AWS / 阿里云 / 腾讯云都有 SDK：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


// Azure Functions 写法（无服务器）
public class HttpExample
{
 [Function("HttpExample")]
 public async Task<HttpResponseData> Run(
 [HttpTrigger(AuthorizationLevel.Function, "get", "post")] HttpRequestData req)
 {
 var response = req.CreateResponse(HttpStatusCode.OK);
 await response.WriteStringAsync("Hello from Azure Functions!");
 return response;
 }
}

⑥ 物联网（IoT）

.NET nanoFramework —— 跑在 STM32 / ESP32 嵌入式芯片
Meadow —— IoT 主板，完整 .NET 运行时
Azure IoT Hub SDK —— 云端接入

⑦ 机器学习

ML.NET —— 微软的机器学习框架，2018 年开源：

1
2
3
4
5
6


// 训练一个情感分析模型
var mlContext = new MLContext();
var data = mlContext.Data.LoadFromTextFile<SentimentData>("sentiment.csv", hasHeader: true);
var pipeline = mlContext.Transforms.Text.FeaturizeText("Features", "Text")
 .Append(mlContext.BinaryClassification.Trainers.SdcaLogisticRegression());
var model = pipeline.Fit(data);

也支持调用 ONNX 模型、TensorFlow .NET 绑定。

⑧ 游戏

Unity 是全球最大游戏引擎（手游市场 50%+），C# 是 Unity 的唯一脚本语言。王者荣耀、原神、纪念碑谷都用 C# / Unity。

四、.NET 选型决策树

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


新项目，应该选什么 .NET？
│
├─ Web / 微服务？
│ ├─ Windows only + 老系统集成 → ASP.NET (.NET Framework 4.8)
│ └─ 跨平台 / 容器 / 云原生 → ASP.NET Core (.NET 8 / 9)
│
├─ 桌面？
│ ├─ 内部工具 / Windows only → WPF / WinForms
│ ├─ 现代 Windows UI → WinUI 3
│ └─ 跨平台桌面 → Avalonia / .NET MAUI
│
├─ 移动？
│ ├─ iOS / Android / Windows 跨平台 → .NET MAUI
│ └─ Unity 游戏 → Unity + C#
│
├─ 嵌入式 / IoT？
│ ├─ 资源极受限（< 256KB RAM）→ C / C++
│ └─ STM32 / ESP32 → .NET nanoFramework
│
└─ ML？
 └─ ML.NET / 调 ONNX / 调 TensorFlow.NET

五、为什么 2018 年 .NET 突然火了

跨平台 + 开源：2014 年 .NET Core 开源后，Linux 服务器也能跑 C#——Linux 工程师不再鄙视 .NET
性能飞升：TechEmpower Round 14 基准测试，ASP.NET Core 超过 Node.js、Go、Java
VS Code + Rider：跨平台 IDE 体验不输 Visual Studio
云原生友好：镜像小、启动快、K8s 一等公民
企业级生态：Entity Framework Core、xUnit、Serilog、MediatR——dotnet add package 一行解决

六、下一步

入门：.NET 官方文档 https://learn.microsoft.com/dotnet/，先跑通 dotnet new web
Web 框架：ASP.NET Core 8 / 9 Minimal API
微服务：Steeltoe（Spring Cloud 之于 Spring Boot）
测试：xUnit + FluentAssertions + NSubstitute
ORM：EF Core（官方）、Dapper（轻量）、FreeSQL（国产）

参考资料

.NET 官方文档：https://learn.microsoft.com/dotnet/
OpenAPI 规范：https://spec.openapis.org/oas/v3.0.3
Swagger 工具链：https://swagger.io/tools/
ASP.NET Core 源码：https://github.com/dotnet/aspnetcore
.NET 基金会：https://dotnetfoundation.org/

文档 on Liangweidong's blog