api接口文档的修改（api接口的简单编写方式）

本篇文章给大家谈谈api接口文档的修改，以及api接口的简单编写方式对应的知识点，希望对各位有所帮助，不要忘了收藏本站喔。 今天给各位分享api接口文档的修改的知识，其中也会对api接口的简单编写方式进行解释，如果能碰巧解决你现在面临的问题，别忘了关注本站，现在开始吧！

本文目录一览：

• 1、如何优雅的“编写”api接口文档
• 2、使用 API Blueprint 来编写 API 接口文档
• 3、什么是接口文档,如何写接口,有什么规范?
• 4、云塔idc如何搞api接口
• 5、apifox接口文档怎么返回响应json对象
• 6、如何使 WebAPI 自动生成漂亮又实用在线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中的数据是对象类型。则需要描述对象中字段的名称、类型、长度、不能为空、默认值、说明。以表格的方式来表达最好。

示例：

二、响应参数

1. 响应 HTTP Body

响应body同请求body一样，需要描述请清除数据的类型。

另外，如果服务会根据不同的http status code 返回不同的数据结构， 也需要针对不同的http status code对内容进行描述。

三、接口说明

说明接口的应用场景，特别的注意点，比如，接口是否幂等、处理是同步方式还是异步方式等。

四、示例

上个示例（重点都用红笔圈出来，记牢了）：

五、接口工具

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

使用 API Blueprint 来编写 API 接口文档

API Blueprint 用来编写API文档的一种标记语言，类似于Markdown，具体的语法规则可以在 API Blueprint documentation 查看，文档里面还有一个简短的 API Blueprint tutorial 建议先仔细阅读一下这个教程。

使用 API Blueprint 文档，配合一些开源的工具可以把接口文档渲染成 html 再搭配一个静态服务器，就可以很方便的共享给同事。

相对于 word 这种富文本格式的文档来说， API Blueprint 是纯文本，这样可以很方便的使用版本控制工具 Git 来控制版本。

另外，配合一些工具，可以直接生成一个 mock data 数据，这样只要和后端的同学约定好接口格式，那么前端再开发的时候可以使用 mock data 数据来做测试，等到后端写好接口之后再做联调就可以了。

API Blueprint 社区提供了一些文本编辑器的插件，可以识别 API Blueprint 语法支持语法高亮。

使用 apiblueprint 编写好文档使用，可以使用开源社区提供的一个工具 aglio 来把接口文档渲染成 html 文件， aglio 还会启动一个静态服务器，这样就可以在浏览器里面查看渲染好的文档了。

aglio 的使用教程，可以直接查看官方开发仓库的 readme 文档。另外，这里也有一份资料 使用API-Blueprint 编写 API 文档 可以参考。

什么是接口文档,如何写接口,有什么规范?

含义是api接口文档的修改：在项目开发中api接口文档的修改，web项目的前后端分离开发，APP开发，需要由前后端工程师共同定义接口，编写接口文档，之后大家都根据这个接口文档进行开发，到项目结束前都要一直维护。

目的是：项目开发过程中前后端工程师有一个统一的文件进行沟通交流开发。项目维护中或者项目人员更迭，方便后期人员查看、维护。

规范是：以/a开头，如果需要登录才能调用的接口(如新增、修改；前台的用户个人信息，资金信息等)后面需要加/u，即：/a/u；中间一般放表名或者能表达这个接口的单词；get方法，如果是后台通过搜索查询列表，那么以/search结尾，如果是前台的查询列表，以/list结尾；url参数就不说了。

API（Application Programming Interface，应用程序接口）是一些预先定义的接口（如函数、HTTP接口），或指软件系统不同组成部分衔接的约定。用来提供应用程序与开发人员基于某软件或硬件得以访问的一组例程，而又无需访问源码，或理解内部工作机制的细节。

应用程序接口又称为应用编程接口，是一组定义、程序及协议的集合，通过 API接口实现计算机软件之间的相互通信。API 的一个主要功能是提供通用功能集。

API同时也是一种中间件，为各种不同平台提供数据共享。程序设计的实践中，编程接口的设计首先要使软件系统的职责得到合理划分。良好的接口设计可以降低系统各部分的相互依赖，提高组成单元的内聚性，降低组成单元间的耦合程度，从而提高系统的可维护性和可扩展性。

云塔idc如何搞api接口

应用程序接口（API 接口）是一组定义、程序及协议的集合，通过 API 接口实现计算机软件之间的相互通信。API 的一个主要功能是提供通用功能集。程序员通过使用 API 函数开发应用程序，从而可以避免编写无用程序，以减轻编程任务。在云服务器中，如果你熟悉网络服务协议和一种以上编程语言，可以使用云服务器 API 管理云上资源和开发自己的应用程序。一般能创建的云服务器实例、磁盘、安全组、快照和实例公网带宽流量等资源，云服务商均有数量和规格限制。关于云服务器api接口的入门使用1.通过使用创建实例 API，提供可用区ID、镜像ID、机型参数等一些必要的信息，即可立开发云主机域名刻创建按量计费的实例。2.如需修改配置，可以使用调整实例配置 API 调整为更高的配置。通过调整实例的机型开发云主机域名来实现CPU和内存的变更。如需关闭，可以使用关闭实例 API。3.在不使用此云服务器时，使用退还实例 API 销毁它。

apifox接口文档怎么返回响应json对象

（1）管理环境--新建环境，或者是本机自带的环境，添加url前缀。host+端口等。
（2）可在全局参数里，添加cookie，和代码传参一样，放在header里。
（3）引用全局参数：{{cookie}}。（和postman相比，少了一个get variable的步骤）。
（4）也可以在全局或者当前环境下，将某个数据设为变量。
（5）apifox在创建新的接口名称后，先保存。可以对文档进行修改和前后置操作。
前置操作：连接数据库，提取变量
后置操作：提取变量断言
APIfox 将开发的接口文档和测试的接口测试结合在一起。
接口文档发生了改变（如参数），接口测试不用改。测试只需要改动测试的前置和断言。
建立一个api文档：输入url，请求参数和响应结果（做测试参考）：
如：响应码：200，选择raw，响应示例，应该输入文字
如：响应码：200，返回的是一个json格式，则内容格式选择json，并可以自动生成mock的值。然后在添加示例里面，可以自动生成响应的示例。（接口文档中返回的响应的格式仅仅是作为格式的参考，是mock的，虚拟的。是方便开发编数据。）
真正的响应值要根据请求参数来。
一个完整的接口测试流程：
先在环境中，输入url前置。然后在新建接口里，输入参数值；之后在后置里面实现断言。

如何使 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
访问 lt;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 文档展示效果 关于api接口文档的修改和api接口的简单编写方式的介绍到此就结束了，不知道你从中找到你需要的信息了吗 ？如果你还想了解更多这方面的信息，记得收藏关注本站。 api接口文档的修改的介绍就聊到这里吧，感谢你花时间阅读本站内容，更多关于api接口的简单编写方式、api接口文档的修改的信息别忘了在本站进行查找喔。

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。