百度知道开放平台openAPI接口规范文档(1.0.1)
如何使用OpenAPI规范API
如何使用OpenAPI规范API开发API（Application Programming Interface，应用程序接口），是构建现代软件的不可或缺的技术组成部分。
由于不同的系统之间需要进行数据和功能的交互，所以需要一个通用的标准，以确保这些交互过程能够顺畅地进行。
OpenAPI规范是一个开放、可重用的标准，用于定义RESTful API的操作和模型，它允许开发者以一种标准化的方式描述API，同时还提供了自我记录、自动生成文档、客户端库的生成等一系列工具。
在此文中，我们将探讨如何使用OpenAPI规范API开发，以及一些最佳实践。
1. 熟悉OpenAPI规范使用OpenAPI规范API，首先要了解OpenAPI规范。
它本质上是一个基于JSON或YAML的架构，用于描述RESTful API。
您需要了解OpenAPI文档中包含的元素和结构，这些概念包括：- Paths：定义API的端点和每个端点的HTTP方法- Parameters：用于传递信息的数据结构- Responses：API返回的结果和状态码。
- Schemas：定义API中使用的数据模型和实体如果您还不太熟悉OpenAPI规范，请花些时间去了解它，并使用该规范创建一些简单的API。
2. 使用现有的API在开始创建自己的API之前，建议从现有的API开始，熟悉使用OpenAPI规范的流程。
通过调用其他开发人员编写的API，您可以获取更多的经验，了解OpenAPI规范的最佳实践和一些问题的注意事项。
可以从Swagger官网上获取一些公共API，例如Twitter API、Google Maps API等，这些API都是使用OpenAPI规范编写的。
3. 编写文档API文档是非常重要的，因为它是与其他开发人员交流和理解您的API的主要方式。
在OpenAPI规范中，可以使用YAML或JSON文件编写文档。
这些文档中必须包含各种端点、参数、响应和Schemas的信息。
接口规范文档
接口规范文档1. 简介。
接口规范文档是软件开发过程中非常重要的一环，它定义了软件系统中各个模块之间的通信方式和数据交换格式。
一个好的接口规范文档可以有效地提高开发效率，降低沟通成本，减少后期的修改和维护工作。
2. 目的。
接口规范文档的主要目的是明确规定软件系统中各个模块之间的通信方式和数据交换格式，以便于开发人员能够按照统一的规范进行开发工作。
同时，接口规范文档也可以作为开发人员和测试人员之间沟通的桥梁，减少因为接口不清晰而导致的开发和测试工作的偏差。
3. 内容。
接口规范文档通常包括以下内容：接口描述，对接口的功能和作用进行详细的描述，包括输入参数、输出参数、返回值等。
接口格式，定义接口的数据交换格式，如JSON、XML等。
接口调用方式，明确规定接口的调用方式，包括请求方法、URL、参数传递方式等。
接口安全性，定义接口的安全机制，包括认证、授权、加密等。
接口错误处理，规定接口返回错误码和错误信息的格式和含义。
接口版本管理，定义接口的版本管理策略，包括版本号的规范和升级方式。
4. 编写规范。
接口规范文档的编写应当遵循一定的规范，以便于开发人员和测试人员能够快速地理解和使用。
具体规范包括：使用简洁明了的语言描述接口的功能和作用，避免使用过于复杂的术语和词汇。
使用统一的格式和风格，包括文档的结构、标题、字体、颜色等。
为每个接口添加详细的注释，包括参数的含义、取值范围、示例等。
定期更新和维护接口规范文档，及时反映系统的变化和需求的变更。
5. 实例。
以下是一个简单的接口规范文档的实例：接口名称，用户登录接口。
接口描述，用户使用用户名和密码进行登录操作，成功登录后返回用户信息。
接口格式，JSON。
接口调用方式，POST。
接口URL，/api/login。
输入参数：username，用户名，字符串类型，必填。
password，密码，字符串类型，必填。
输出参数：code，返回码，整数类型，0表示成功，非0表示失败。
接口规范文档
接口规范文档接口规范文档1. 引言接口规范文档是为开发人员提供开发接口时遵循的标准和规范。
本文档详细描述了接口的命名、参数、返回值、错误处理、安全性等方面的规范。
遵循该规范可以保证接口的一致性、可读性和易用性。
2. 接口命名规范2.1 接口名应使用动词或动词短语，如getUser、createOrder。
2.2 接口名应使用驼峰命名法，首字母小写，例如getUserInfo、createUser。
2.3 接口名应能准确地反映接口的功能。
3. 参数规范3.1 参数应使用英文单词，并采用驼峰命名法。
3.2 参数应有具体的类型，如String、Integer、List等。
3.3 参数应有明确的说明，包括是否必填、最大长度等限制。
3.4 参数应按照功能和逻辑进行分组。
4. 返回值规范4.1 返回值应使用具体的类型，如String、Integer、List等。
4.2 返回值应有明确的说明，包括返回值的含义、格式等。
4.3 返回值应符合业务逻辑和功能需求。
5. 错误处理规范5.1 错误码应采用统一的格式，如4xx代表客户端错误，5xx 代表服务器错误。
5.2 错误信息应精简明了，便于开发人员查找和定位问题。
5.3 错误处理应返回明确的错误信息，便于用户理解和处理。
6. 安全性规范6.1 接口应有访问权限控制，确保只有授权用户可以访问。
6.2 接口应对敏感数据进行加密和处理，保护用户的个人信息安全。
6.3 接口应有防止恶意请求的措施，如验证码、限制访问频率等。
7. 版本管理规范7.1 接口的版本号应采用标准格式，如v1、v2.1等。
7.2 接口的变更应进行版本管理，遵循向后兼容的原则。
8. 接口文档编写规范8.1 接口文档应使用简洁明了的语言，避免使用过于专业或复杂的术语。
8.2 接口文档应包括接口的功能描述、参数说明、示例代码等内容。
8.3 接口文档应更新及时，保证与实际开发的接口一致。
以上是接口规范文档的主要内容，遵循该规范可以提高接口的开发效率和质量，减少沟通成本和问题发生率。
接口规范文档
接口规范文档
接口规范文档是描述如何使用接口以及接口的行为和功能的文档。
接口规范文档通常包括以下内容：
1. 接口描述：对接口的功能和作用进行详细描述。
2. 接口地址：指定接口的URL或者路径。
3. 接口请求方法：指定接口的请求方法，如GET、POST等。
4. 请求参数：列出接口需要的请求参数及其类型、是否必需、参数的取值范围等信息。
5. 请求示例：提供请求示例，展示如何构建请求参数以及请求的格式。
6. 响应参数：列出接口的响应参数及其类型、参数的含义等信息。
7. 响应示例：提供响应示例，展示接口请求后的返回结果及其格式。
8. 错误码说明：列出接口可能返回的错误码及其含义，方便开发者进行错误处理。
9. 接口权限：指定接口的访问权限，如是否需要认证、角色要求等。
10. 接口示意图：可选项，展示接口的流程和数据交互方式的
图表。
接口规范文档的编写需要考虑到与项目相关人员（如开发人员、测试人员、产品经理等）的沟通与调整，确保对接口的需求和使用方式有一个统一的理解。
同时，接口规范文档应该尽可能清晰简洁，方便开发人员理解和使用。
openapi 标准
OpenAPI是一种规范，它定义了构建、描述、产生、可视化RESTful 风格的Web服务的接口。
它可以帮助人和计算机发现和理解服务，使得使用最少的实现逻辑来理解远程服务并与之交互成为可能。
OpenAPI标准的内容包括使用规定的格式来描述HTTP RESTful API的定义，以此来规范RESTful服务开发过程。
它使用JSON或YAML来描述一个标准的、与编程语言无关的HTTP API接口。
一个典型的OpenAPI文档包含至少一个paths字段和一个components字段或一个webhooks字段。
OpenAPI文档编写在一个.json或.yaml中，推荐将其命名为openapi.json或openapi.yaml。
OpenAPI文档其实就是一个单一的JSON对象，其中包含符合OpenAPI规范中定义的结构字段。
此外，OpenAPI还有以下一些特点：1. OpenAPI是规范化描述API领域应用最广泛的行业标准，由OpenAPI Initiative(OAI)定义并维护，同时也是Linux基金会下的一个开源项目。
2. OpenAPI规范最初基于SmartBear Software在2015年捐赠的Swagger规范演变而来，目前最新的版本是v3.1.0。
3. OpenAPI就是用来定义HTTP接口文档的一种规范，大家都按照同一套规范来编写接口文档，能够极大的减少沟通成本。
4. OpenAPI规范包含非常多的细节，比如每个路径参数必须对应一个Path Item或Operations对象，例外的是如果路径项为空(例如由于ACL约束)，则不需要匹配的路径参数。
总的来说，OpenAPI是一种编写Web服务接口的规范，它使用标准的格式来描述和定义HTTP API，使得人和计算机可以更容易地发现和理解服务。
OpenAPI安全认证库(C#)V1.0.1开发指南(海康威视iSecure Center)
备注： 使用其它接口之前需要通过此接口设置平台信息。
示例（使用 HTTPS 协议）：
详见基于 OpenAPI 安全认证库（C#）接口的使用示例。
2.2 POST 请求接口
接口名称： byte[] HttpPost(string uri, string body, int timeout)
参数说明： [in] uri ： GET 请 求 的 URI ， 需 要 自 行 拼 接 参 数 ， 如 /artemis/api/resource/v1/cameras/indexCode?cameraIndexCode=a10cafaa777c49a5af92c165c95970e0 [in] timeout：请求超时时间，单位：秒
2. 接口定义
2.1 设置平台信息接口
接口名称： void SetPlatformInfo(string appkey, string secret, string ip, int port = 443, bool isHttps = true)
接口描述： 统一设置 HTTP/HTTPS 请求的平台参数信息。
VS 版本较高需要升级，可能存在警告或者错误的情况，请自行根据升级结果文档解决），如下图：
图 3.2.2-1 HttpUtillib Demo
2、 选择 Any CPU 模式下的平台。选择“生成”->“生成 HttpUtillib”（或英文模式下的“Build”->“Build HttpUtillibTest”），生成的 EXE 位于 bin 目录下。生成 HttpUtillib 以及生成结果如下图：
3.1 示例：POST 请求根据监控点编号查询监控点信息
// step1：组装POST请求body string body = "{\"cameraIndexCode\": \"a10cafaa777c49a5af92c165c95970e0\"}"; // step2：填充Uri string uri = "/artemis/api/resource/v1/cameras/indexCode"; // step3：发起POST请求，超时时间15秒，返回响应字节数组 byte[] result = HttpUtillib.HttpPost(uri, body, 15);
openapi接口使用方法
OpenAPI接口使用方法1. 什么是OpenAPI接口OpenAPI（开放API）接口是一种用于不同软件系统之间进行数据交互的标准化接口。
它允许开发者在不了解系统内部实现细节的情况下，通过调用提供的API接口，获取系统所提供的各种功能和数据。
OpenAPI接口的使用方便、灵活，可以为开发者提供各种服务，如查询、创建、更新和删除数据等。
2. OpenAPI接口的优势•标准化接口：OpenAPI接口遵循一定的标准规范，使用起来更加统一和规范，降低了开发者的学习成本；•提供丰富功能：通过OpenAPI接口，开发者可以获取到系统中各种功能和数据，极大地丰富了应用程序的功能；•提高开发效率：使用OpenAPI接口可以避免重复劳动，开发者可以重用已经编写好的接口，进一步提高开发效率；•降低系统耦合性：OpenAPI接口将系统内部功能封装成独立的接口，使得系统之间的耦合度降低，更方便维护和升级。
3. OpenAPI接口的使用步骤使用OpenAPI接口一般包括以下几个步骤：步骤1：申请API密钥访问该API接口的前提是要求开发者注册并获得一个API密钥。
你需要提供一些必要的信息，如应用程序名称、所属平台等。
注册成功后，将会收到一个唯一的API密钥，用于在使用API时进行身份认证。
步骤2：查看API文档在获得API密钥后，开发者需要查看API文档。
API文档中包含了API接口的详细信息，如接口的URL、请求参数、响应格式等。
开发者需要仔细阅读文档，了解API接口的使用方法和限制。
步骤3：构建API请求构建API请求包括以下几个关键要素：•URL：API接口的URL，用于指定请求的资源位置和操作。
根据API文档提供的信息，将URL进行相应的参数替换，构建出完整的请求URL；•请求方法：API接口支持的请求方法，如GET、POST、PUT、DELETE等。
根据API文档中指定的请求方法，选择合适的方法；•请求头：包含了一些必要的信息，如API密钥、请求格式等。
ELN--OPEN API接口规范
上海时代光华OpenAPI接口规范2008-11-18Revision History目录一、功能表 (4)1.1 validateUser (5)1.2 getOrganizes (6)一、功能表（方法参数见下详细说明）1.1请求到ISV的URL：●userId:用户在ELN上的唯一ID。
●coopCode:用户所在公司ID。
●appId:ELN为每个ISV服务生成的ID。
●token： DES(userId=””&coopCode=””&appId=””&time=””)time: 1970-01-01 00:00:00到当前时间的秒数。
1.2 ISV接受请求，组合参数请求ASSP验证调用validateUser请求就是发送一个HTTP:1.1 POST或者GET请求到ASSP,实●userId:用户在ELN上的唯一ID。
●coopCode:用户所在公司ID。
●appId:ELN为每个ISV服务生成的ID。
●token： DES(userId=””&coopCode=””&appId=””&time=””)time: 1970-01-01 00:00:00到当前时间的秒数。
●time:返回时间戳（秒）。
●isvCoopCode:服务提供商的coopCode。
●isvSecret：ELN为每个注册的服务生成的唯一的安全码。
●elnApiName：服务名。
●sign:摘要。
必须带上这个字符串，且数据正确，才能得到正确的ASSP响应。
Sign生成的算法对于所有接口适用，简单的说就是把所有需要的参数，按字段KEY升序排列，再直接字符串连接组成这种串格式：isvSecret参数1值1参数2值2..参数7值7参数8值8的形式，如果有个参数7的值为空，则空值还是可以拼接到字符串上去：isvSecret参数1值1参数2值2..参数7参数8值8返回结果为XML。
- 1、下载文档前请自行甄别文档内容的完整性，平台不提供额外的编辑、内容补充、找答案等附加服务。
- 2、"仅部分预览"的文档,不可在线预览部分如存在完整性等问题,可反馈申请退款(可完整预览的文档不适用该条件!)。
- 3、如文档侵犯您的权益，请联系客服反馈,我们会尽快为您处理(人工客服工作时间：9:00-18:30)。
百度知道开放平台OPEN API接口规范文档V1.0.1系统名称百度知道开放平台OPEN API服务接口项目负责人作者陈霖文档提交日期2010-11-04百度在线网络技术（北京）有限公司(版权所有,翻版必究)修改记录No 修改后版本号修改内容简介修改日期修改人1 1.0 百度知道OPEN API服务接口2010-11-04 陈霖2 1.0.1 baidu.zhidao.getQuestionInfo修改baidu.zhidao.setBestAnswer修改2011-02-17 王兴目录1背景 (6)2规范适用对象说明 (6)3名词解释 (6)4请求数据包格式规范 (6)4.1URL (6)4.2参数 (7)4.2.1系统级参数 (7)4.2.2业务级参数的通用约定 (7)4.2.3参数签名算法 (7)5响应数据包格式规范 (8)5.1XML输出格式 (8)5.2json输出格式 (9)5.3错误响应输出格式 (9)6错误码定义 (9)7API接口细则 (10)7.1baidu.zhidao.getCatalogInfo (10)7.1.1功能 (10)7.1.2参数 (10)7.1.3返回值 (11)7.2baidu.zhidao.getQuestionList (11)7.2.1功能 (11)7.2.2参数 (11)7.2.3返回值 (11)7.3baidu.zhidao.getQuestionSearch (12)7.3.1功能 (12)7.3.2参数 (12)7.3.3返回值 (12)7.4baidu.zhidao.getQuestionInfo (13)7.4.1功能 (13)7.4.2参数 (13)7.4.3返回值 (13)7.5baidu.zhidao.getQuestionAnswer (14)7.5.1功能 (14)7.5.2参数 (14)7.5.3返回值 (15)7.6baidu.zhidao.getUserInfo (15)7.6.1功能 (15)7.6.2参数 (15)7.6.3返回值 (15)7.7baidu.zhidao.getUserQuestionList (16)7.7.1功能 (16)7.7.2参数 (16)7.7.3返回值 (16)7.8baidu.zhidao.getUserAnswerList (17)7.8.1功能 (17)7.8.2参数 (17)7.8.3返回值 (17)7.9baidu.zhidao.getRecommend (18)7.9.1功能 (18)7.9.2参数 (18)7.9.3返回值 (18)7.10baidu.zhidao.getUserScoreRank (19)7.10.1功能 (19)7.10.2参数 (19)7.10.3返回值 (19)7.11baidu.zhidao.changeUserWealth (20)7.11.1功能 (20)7.11.2参数 (20)7.11.3返回值 (21)7.12baidu.zhidao.setBestAnswer (21)7.12.1功能 (21)7.12.2参数 (21)7.12.3返回值 (21)7.13baidu.zhidao.question (21)7.13.1功能 (21)7.13.2参数 (22)7.13.3返回值 (22)7.14baidu.zhidao.answer (22)7.14.1功能 (22)7.14.2参数 (22)7.14.3返回值 (23)8第三方提供API接口细则 (23)8.1回答反馈接口 (23)8.2动作提醒接口 (25)9附件及参考资料 (25)1背景本文旨在为第三方合作站点应用访问知道频道开放服务提供统一的HTTP接口调用与交互规范。
本文中描述的规范包括知道频道的查询分类树信息、问题列表查询接口、检索查询接口、查询精彩推荐接口、查询用户信息接口、查询用户提问回答信息接口、查询用户排行榜接口、提问接口、回答接口、消息提醒接口、财富兑换接口和采纳最佳答案接口。
2规范适用对象说明本规范仅适用于由服务器端发起调用请求、POST提交数据以及GET请求文本数据结果的Open API。
3名词解释●百度知道：●各网站的百度知道频道：●API KEY：注册API合作时由百度的OPEN API平台分配的唯一标识一个应用的字符串，又称应用公钥●API SECRET：注册API合作时由百度的OPEN API平台分配的应用密钥，用于平台与合作站点之间通信时的参数签名4请求数据包格式规范4.1URL按照百度Open API规范，百度知道频道OPEN API提供如下REST风格的HTTP接口：/restserver/zhidao?{query_string}query_string由系统级参数部分和具体Open API调用参数部分组成，以key1=value&key2=value2&…表示，对于采用POST请求的Open API，query_string部分则是在POST 请求体里。
所有查询类的Open API接口既支持POST，也支持GET方式，提交类的OPEN API接口仅支持POST方式。
4.2参数4.2.1系统级参数以下参数是由百度Open API平台系统定义的，百度知道频道需要支持这些参数以便接入该平台提供开放接口。
百度知道频道采用应用授权认证接口方式，合作初始百度知道开放平台代第三方站点申请应用分配api_key和参数签名密钥api_secret。
表格4-1 API系统级参数参数名类型是否必需描述api_key string 是注册应用时分配到的api keymethod string 是采取baidu.zhidao.getQuestionList这样的命名空间方式制定方法名call_id uint 是时间戳，系统时间的秒值,同个应用的不同api请求的time值应该是递增的, 用于防replay攻击format string 否响应包格式，可以是xml（默认）或jsonie string 否API调用请求包的编码类型，支持UTF-8和GBKbd_sig string 是参数签名，对bd_sig外所有参数串的签名，包括业务级的参数。
4.2.2业务级参数的通用约定百度知道频道遵守百度Open API规范中业务级通用参数的约定。
表格4-2 业务级参数的通用约定参数名类型描述page_no Int 用于支持分页的api，默认为1，表示第几页page_size Int 用于支持分页的api，表示每页返回多少条数据，默认以及上限为254.2.3参数签名算法参数签名生成算法采取如下方式（PHP版），其它语言根据注释描述完成等同功能：//param_array是key-value形式的参数数组，不包括api_secret密钥本身//secret是合作申请成功后分配的api_secret密钥function generate_sig($param_array, $secret) {$str = '';//对param_array中的参数名称进行升序排序ksort($param_array);//按照如下格式转换数组为string格式foreach ($param_array as $k=>$v) {$str .= "$k=$v";}//string末端补充api_secret密钥$str .= $secret;//生成32位小写MD5为最终的数据签名return md5($str);}注：密钥是百度知道频道分配给第三方应用的secret_key，该算法返回的结果便是系统级参数中的bd_sig。
5响应数据包格式规范响应数据包的格式由调用时传递的format参数指定（默认为xml格式），无论是xml格式还是json格式，输出内容都是UTF-8格式。
目前，百度知道频道目前支持xml、json格式。
5.1XML输出格式●文档编码格式UTF-8●接口的返回数据中，数组对应的xml节点包含list=”true”属性，其子节点的标签名跟对应的数据有联系，并且同个数组内的同级节点的标签名一致。
例如表示问题标题列表对应的xml输出可能为：<questionList list="true"><title><![CDATA[北京一共有几个区？]]></title><title><![CDATA[百度大厦的地址是什么？]]></title></questionList>●接口的返回数据中，对象类型和普通数据类型数据（string，int，double，bool）对应的xml节点不包含list属性或者list属性值为false，节点标签名具有实际意义，与数据所描述的信息相符。
例如，表示问题的数据对应的xml输出为：<question list=”false”><title><![CDATA[百度大厦的地址是什么？]]></title><url><![CDATA[/question/b231e997ade585b3e99481e59bbd7a62310200]]</url><content><![CDATA[如题，百度大厦地址在]]</ content ></question>5.2json输出格式API调用时如果传递format参数为json（大小写不敏感），则正常响应包符合如下规范的json 字符串：●http响应头中的Content-Type指定为application/json,charset=utf-8●字符串编码格式是UTF-8字符串内容是XML输出数据所对应的PHP数组的标准JSON字符串5.3错误响应输出格式错误响应输出内容符合以下规范：●返回内容由error_code, error_msg, request_args这3个属性组成，分别用于描述错误码，错误信息，以及调用Open API时所传递的所有参数的信息。
●request_args属性是一个数组，由n个包含key和value属性的对象组成例如，假设第三方应用调用baidu.zhidao.getQuestionList接口时传递的参数api_key无效，则其对应的xml格式的错误响应包为如下格式：<?xml version="1.0" encoding="UTF-8"?><baidu_zhidao_getQuestionList_response><error_code>101</error_code><error_msg>Invalid API key</error_msg><request_args list="true"><arg><key><![CDATA[cid]]></key><value><![CDATA[249]]></value></arg><arg><key><![CDATA[method]]></key><value><![CDATA[baidu.zhidao.getQuestionLis]]></value></arg></request_args></ baidu_zhidao_getQuestionList_response >Json格式的字符串内容是XML输出数据所对应的PHP数组的标准JSON字符串6错误码定义百度开放知道OPEN API调用过程中可能会返回的错误码定义如下表所示：error_code error_msg Description0 Success成功1 Unknown error未知错误2 Service temporarily unavailable后端服务暂时不可用3 Unsupported openapi method Open api接口不被支持4 Open api request limit reached 应用对open api接口的调用请求数达到上限5 Unauthorized client IP address:%s open api调用端的IP未被授权100 Invalid parameter参数无效或缺失101 Invalid API key Api key无效103 Invalid call_id parameter Call_id参数无效或已被使用过104 Incorrect signature签名无效105 Too many parameters参数过多106 Unsupported signature method参数签名算法未被平台所支持200 No permission to access data没有权限访问数据900 No such application exists 应用不存在12001 Parameters format error 必选参数格式错误12002 Operate for invalid question 问题生命已经结束12003 Query for invalid question status 查询问题状态错误12004 Post str too long or short 提交字符串长度不合法12005 Invalid qid or aid 所找问题、回答已失效或不存在12006 Answer user is the asker or asked 回答用户是提问者或者已经回答过12100 Invalid user 无效的用户信息12101 User wealth is not enough 用户财富不足12102 Invalid account system 无效的账户系统7API接口细则以下接口返回数据均是以XML格式为demo，JSON格式的字符串内容是XML输出数据所对应的PHP数组的标准JSON字符串。