在线编辑api接口文档（在线编辑api接口文档怎么编辑）

网友投稿 442 2023-02-18

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

本文目录一览：

1、如何优雅的“编写”api接口文档
2、如何使 WebAPI 自动生成漂亮又实用在线API文档
3、在定制开发程序中接入腾讯文档

如何优雅的“编写”api接口文档

1. 拼写要准确
接口函数一旦发布就不能改了，要保持兼容性，拼写错误也不能改了，所以要仔细检查拼写，否则会被同行嘲笑很多年。
著名悲剧：unix 的 creat
2. 不仅是英文单词不要拼错，时态也不要错。
比如：
返回bool的判断函数，单数要用 is 复数要用are，这样你的命名就和文档中的描述保持了一致性。
表示状态的变量或者函数要注意时态，比如 onXxxxChanged 表示xxx已经变化了，isConnecting表示正在连接。
正确的时态可以给使用者传递更丰富的信息。
3. 函数最好是动宾结构
动宾结构就是 doSomething，这样的函数命名含义明确
比如： openFile, allocBuffer, setName
如果这个函数的动词宾语就是这个对象本身，那么可以省略掉宾语
4. 属性命名最好是定语+名词
比如 fileName, maxSize, textColor
5. 不要用生僻单词，这不是秀英语的地方，也不要用汉语拼音
比如：rendezvous，估计大多数人要去查词典才知道什么意思，这个词源自法语，是约会的意思。
Symbian OS里有个用它命名的函数，开发Symbian的是英国人，也许人家觉得很平常吧，反正我是查了词典才知道的。
6. 不要自己发明缩写
除非是约定俗成已经被广泛使用的缩写，否则老老实实用完整拼写。
坏例子: count-cnt, manager-mngr password-pw button-btn
现代的IDE都有很好的自动完成功能，名字长一点没关系的，可读性更重要。
7. 保持方法的对称性，有些方法一旦出现就应该是成对的，
比如有open就要有close，有alloc就要有free，有add就要有remove，这些单词基本是固定搭配的，使用者就很容易理解。
如果 open对应clear就有点让人困惑了。

在线编辑api接口文档（在线编辑api接口文档怎么编辑）

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

1.1 SwaggerUI
SwaggerUI 是一个简单的Restful API 测试和文档工具。简单、漂亮、易用（官方demo）。通过读取JSON 配置显示API. 项目本身仅仅也只依赖一些 html,css.js静态文件. 在线编辑api接口文档你可以几乎放在任何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请求头中是再好不过在线编辑api接口文档了。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 文档展示效果

在定制开发程序中接入腾讯文档

腾讯文档是腾讯于2018年4月推出的一款可多人在线协作的免费文档产品。目前支持在线文档、表格、收集表、PPT、PDF、思维导图、流程图七种文档品类，同时为合作伙伴提供丰富的API接口，只需轻量级开发即可接入自身产品，补齐文档解析、在线编辑、长内容储存、远程演示、内容读取、信息收集等能力。

针对文档功能，提供完善的编辑能力，轻松设置文字样式和段落格式，添加图片、链接和表格等，可快速导入导出word文档，便捷追溯历史版本，随时随地与在线编辑api接口文档他人协作，轻松制作生动的文档。

针对表格功能，支持多人同时处理同一份表格，可一键转为收集表格，高效收集信息和数据，提供数据验证、条件格式、筛选排序、200多种函数及常用图表等多种专业功能，随时随地处理数据。

针对幻灯片功能，支持常用的形状和动画，可导入本地PPT，随时随地协作编辑，高效汇总文档，分享链接即可邀请好友在线远程演示，手机端、电脑端均可查看。

提供的在线表格收集功能，一张收集表可收集百万份信息，结果实时汇总到在线表格，数据实时分析在线编辑api接口文档；提供单选、多选、图片、温度、位置等丰富问题类型，支持数据校验，高效收集信息。

同时腾讯文档也提供了思维导图的功能，提供基础图、树状图、组织结构图等多种图形结构，可插入图片、链接、备注、图标等丰富内容，支持导入XMind文档；可多人在线协作，云端存储，多设备同步；轻松构思，让你有序整理和标记思路。

用户只需在官网按指引填写注册信息，并完成对公账号打款验证即可接入腾讯文档开放平台API。腾讯文档开放平台持续迭代更新，现阶段暂时面向企业主体用户开放API接入，详细流程可查看：腾讯文档开放平台企业主体注册流程。企业主体用户按指引填写注册信息时，需要上传工商营业执照，系统会在3个工作日内完成工商信息审核。工商信息审核通过后，企业主体用户需要填写对公账号信息，提交后系统会向对公账号打一笔1元以下的资金，对公账号会在2个工作日内收到这笔资金，只需回写正确的金额即可认证成功，开始使用开腾讯文档放平台能力。企业全程无需支付任何费用。

目前腾讯文档支持API接入和小程序接入。腾讯文档开放平台开发文档网址如下：

https://docs.qq.com/open/wiki/

针对该文档，我们可以采用相关的开发语言进行集成类的开发。例如我们在C#下集成的TencentDocument类库。关于在线编辑api接口文档和在线编辑api接口文档怎么编辑的介绍到此就结束了，不知道你从中找到你需要的信息了吗？如果你还想了解更多这方面的信息，记得收藏关注本站。在线编辑api接口文档的介绍就聊到这里吧，感谢你花时间阅读本站内容，更多关于在线编辑api接口文档怎么编辑、在线编辑api接口文档的信息别忘了在本站进行查找喔。

标签：接口文档 api接口文档 api 接口代码

暂时没有评论，来抢沙发吧~

在线编辑api接口文档（在线编辑api接口文档怎么编辑）

如何优雅的“编写”api接口文档

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

在定制开发程序中接入腾讯文档

多平台统一管理软件接口，如何实现多平台统一管理软件接口

Flask接口签名sign原理与实例代码浅析

java中的接口是类吗

推荐文章

接口调用是什么意思？几种常用接口调用方式

接口设计原则

8款在线 API 接口文档管理工具

api管理系统是什么？

什么是接口调试？接口调试的步骤有哪些？

api 接口管理系统有哪些？

接口测试有几种测试方法

API文档生成工具有哪些？

微服务和api网关区别

交换机配置步骤

最近发表

热评文章

在线接口文档管理工具推荐，支持在线测试，HTTP接口

开源的在线接口文档wiki工具Mindoc的介绍与使

如何优雅的进行接口设计？接口设计的六大原则是什么？

什么是API测试,api检测公司

软件接口设计怎么做？前后端分离软件接口设计思路

接口管理平台推荐，几大接口管理平台总有一款适合你！