api文件制作

Ⅰ 如何快速编写api文档

刚开始写接口文档的服务端同学，很容易按着代码的思路去编写接口文档，这让客户端同学或者是服务对接方技术人员经常吐槽，看不懂接口文档。这篇文章提供一个常规接口文档的编写方法，给大家参考。

推荐使用的是docway写接口文档，方便保存和共享，支持导出PDF MARKDOWN，支持团队项目管理。

一、请求参数

1. 请求方法

• GET

用于获取数据

• POST

用于更新数据，可与PUT互换，语义上PUT支持幂等

• PUT

用于新增数据，可与POST互换，语义上PUT支持幂等

• DELETE

用于删除数据

• 其他

其他的请求方法在一般的接口中很少使用。如：PATCH HEAD OPTIONS

2. URL

url表示了接口的请求路径。路径中可以包含参数，称为地址参数，如**/user/{id}**，其中id作为一个参数。

3. HTTP Header

HTTP Header用于此次请求的基础信息，在接口文档中以K-V方式展示，其中Content-Type则是一个非常必要的header，它描述的请求体的数据类型。

常用的content-type：

• application/x-www-form-urlencoded

请求参数使用“&”符号连接。

• application/json

内容为json格式

• application/xml

内容为xml格式

• multipart/form-data

内容为多个数据组成，有分隔符隔开

4. HTTP Body

描述http body，依赖于body中具体的数据类型。如果body中的数据是对象类型。则需要描述对象中字段的名称、类型、长度、不能为空、默认值、说明。以表格的方式来表达最好。

示例：



五、接口工具

推荐使用的是http://docway.net（以前叫小幺鸡） 写接口文档，方便保存和共享，支持导出PDF MARKDOWN，支持团队项目管理。

Ⅱ 如何使 WebAPI 自动生成漂亮又实用在线API文档

1.1 SwaggerUI

SwaggerUI 是一个简单的Restful API 测试和文档工具。简单、漂亮、易用（官方demo）。通过读取JSON 配置显示API. 项目本身仅仅也只依赖一些 html,css.js静态文件. 你可以几乎放在任何Web容器上使用。

1.2 Swashbuckle

Swashbuckle 是.NET类库,可以将WebAPI所有开放的控制器方法生成对应SwaggerUI的JSON配置。再通过SwaggerUI 显示出来。类库中已经包含SwaggerUI 。所以不需要额外安装。

2.快速开始

创建项目 OnlineAPI来封装网络音乐服务(示例下载) ，通过API可以搜索、获取音乐的信息和播放连接。

我尽量删除一些我们demo中不会用到的一些文件，使其看上去比较简洁。

WebAPI 安装 Swashbuckle

Install-Package Swashbuckle

代码注释生成文档说明。
Swashbuckle 是通过生成的XML文件来读取注释的，生成 SwaggerUI，JSON 配置中的说明的。
安装时会在项目目录 App_Start 文件夹下生成一个 SwaggerConfig.cs 配置文件，用于配置 SwaggerUI 相关展示行为的。如图：

将配置文件大概99行注释去掉并修改为
c.IncludeXmlComments(GetXmlCommentsPath(thisAssembly.GetName().Name));

并在当前类中添加一个方法

/// <summary>
/// </summary>
/// <param name="name"></param>
/// <returns></returns>
protected static string GetXmlCommentsPath(string name)
{
return string.Format(@"{0}\bin\{1}.XML", AppDomain.CurrentDomain.BaseDirectory, name);
}

紧接着你在此Web项目属性生成选卡中勾选 “XML 文档文件”，编译过程中生成类库的注释文件

添加网络音乐 3个API

访问 http://<youhost>/swagger/ui/index,最终显示效果

我们通过API 测试API 是否成功运行

3.添加自定义HTTP Header

在开发移动端 API时常常需要验证权限，验证参数放在Http请求头中是再好不过了。WebAPI配合过滤器验证权限即可

首先我们需要创建一个 IOperationFilter 接口的类。IOperationFilter
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Http;
using System.Web.Http.Description;
using System.Web.Http.Filters;
using Swashbuckle.Swagger;

namespace OnlineAPI.Utility
{
public class HttpHeaderFilter : IOperationFilter
{
public void Apply(Operation operation, SchemaRegistry
schemaRegistry, ApiDescription apiDescription)
{
if (operation.parameters == null) operation.parameters = new
List<Parameter>();
var filterPipeline =
apiDescription.ActionDescriptor.GetFilterPipeline();
//判断是否添加权限过滤器
var isAuthorized = filterPipeline.Select(filterInfo =>
filterInfo.Instance).Any(filter => filter is IAuthorizationFilter);
//判断是否允许匿名方法
var allowAnonymous =
apiDescription.ActionDescriptor.GetCustomAttributes<AllowAnonymousAttribute>().Any();

if (isAuthorized && !allowAnonymous)
{
operation.parameters.Add(new Parameter
{
name = "access-key",
@in = "header",
description = "用户访问Key",
required = false,
type = "string"
});
}
}
}
}

在 SwaggerConfig.cs 的 EnableSwagger 配置匿名方法类添加一行注册代码
c.OperationFilter<HttpHeaderFilter>();

添加Web权限过滤器
using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Text;
using System.Web;
using System.Web.Http;
using System.Web.Http.Controllers;
using Newtonsoft.Json;

namespace OnlineAPI.Utility
{
/// <summary>
///
/// </summary>
public class AccessKeyAttribute : AuthorizeAttribute
{
/// <summary>
/// 权限验证
/// </summary>
/// <param name="actionContext"></param>
/// <returns></returns>
protected override bool IsAuthorized(HttpActionContext actionContext)
{
var request = actionContext.Request;
if (request.Headers.Contains("access-key"))
{
var accessKey = request.Headers.GetValues("access-key").SingleOrDefault();
//TODO 验证Key
return accessKey == "123456789";
}
return false;
}

/// <summary>
/// 处理未授权的请求
/// </summary>
/// <param name="actionContext"></param>
protected override void HandleUnauthorizedRequest(HttpActionContext actionContext)
{
var content = JsonConvert.SerializeObject(new {State = HttpStatusCode.Unauthorized});
actionContext.Response = new HttpResponseMessage
{
Content = new StringContent(content, Encoding.UTF8, "application/json"),
StatusCode = HttpStatusCode.Unauthorized
};
}
}
}

在你想要的ApiController 或者是 Action 添加过滤器
[AccessKey]

最终显示效果

4.显示上传文件参数

SwaggerUI 有上传文件的功能和添加自定义HTTP Header 做法类似，只是我们通过特殊的设置来标示API具有上传文件的功能
using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.Http.Description;
using Swashbuckle.Swagger;

namespace OnlineAPI.Utility
{
/// <summary>
///
/// </summary>
public class UploadFilter : IOperationFilter
{

/// <summary>
/// 文件上传
/// </summary>
/// <param name="operation"></param>
/// <param name="schemaRegistry"></param>
/// <param name="apiDescription"></param>
public void Apply(Operation operation, SchemaRegistry schemaRegistry, ApiDescription apiDescription)
{
if (!string.IsNullOrWhiteSpace(operation.summary) && operation.summary.Contains("upload"))
{
operation.consumes.Add("application/form-data");
operation.parameters.Add(new Parameter
{
name = "file",
@in = "formData",
required = true,
type = "file"
});
}
}
}
}

在 SwaggerConfig.cs 的 EnableSwagger 配置匿名方法类添加一行注册代码
c.OperationFilter<UploadFilter>();

API 文档展示效果

Ⅲ ApiPost 快速生成在线接口文档!!

探索ApiPost：在线接口文档生成神器，助你轻松开发与管理

ApiPost，一款专为API开发者和测试人员量身打造的高效工具，它不仅具备强大的调试功能，还提供一键生成美观、易读的在线文档，让团队协作变得更加顺畅。无论是后台接口开发者还是前端工程师，它都能成为你的得力助手。

一、Apipost的全能魅力

ApiPost不仅支持POST、GET、PUT等常见的HTTP请求模拟，还内置了文档编写功能，让你在调试接口的同时，轻松撰写详细的注释，生成出专业级别的在线文档。通过直观的界面，你可以快速上手并掌握其基本操作。

二、下载与安装

下载Apipost非常简单，只需访问官方网站（无需赘述链接），根据你的操作系统（Windows、Mac或Linux）下载对应的安装包，几分钟就能搞定。官方文档详尽丰富，助你无缝集成到开发流程中。

三、常用操作详解

初次使用Apipost，你需要注册并创建项目，通过左侧菜单轻松进入API控制台。除了基础的接口发送和文档生成，还有更多实用功能等你探索。例如，导入参数时，无论是key-value还是JSON格式，Apipost都能快速处理，大大节省时间。

四、操作技巧分享

1. 参数导入便捷 - Apipost支持一键导入请求头、查询参数和body的参数，无论是浏览器控制台的格式还是JSON格式，只需一键导入，无需逐个输入。

2. 智能参数注释 - 参数描述自动识别和保存，减少重复劳动。只需为参数添加一次注释，后续遇到相同参数时，Apipost会自动提示，让文档编写更加高效。

3. 定位接口目录 - 利用"定位到当前接口目录"功能，轻松找到工作中的接口文件，提高开发效率。

4. 在线文档生成与分享 - 新版Apipost支持一键生成并分享文档，设置链接权限和有效期，方便他人查看和协作。

结语：发现更多实用小功能

这只是Apipost众多实用功能的冰山一角，它还提供了更多贴心的设计，例如快速克隆项目、支持RESTful风格的路径变量等，帮助你更好地管理和优化接口开发。赶快下载Apipost，让接口文档生成和管理变得轻松愉快吧！