OpenAPI平台构建与在线文档

最新推荐文章于 2024-08-05 17:13:21 发布

chuangfei7389

最新推荐文章于 2024-08-05 17:13:21 发布

阅读量1.3k

点赞数

文章标签： json java javascript ViewUI

原文链接：https://my.oschina.net/yangty2017/blog/1603071

版权

本文详细介绍了如何使用apidoc构建在线接口文档，包括apidoc的安装、文档编写规则和生成流程。此外，文章重点讨论了接口安全设计规范，从完全开放的接口到接口参数加密、时效性验证、私钥以及HTTPS的使用，逐步提升安全性。还提到了接口参数签名的实现思路和算法过程，并给出了接口开发中的注意事项和签名验证方法。

摘要由CSDN通过智能技术生成

1. 在线接口文档生成

OpenAPI第三方接口平台集成了apidoc作为在线文档系统。

apidoc是一个轻量级的在线REST接口文档生成系统，可以根据其特定的规则的代码注释来生成静态网页。

同时apidoc支持多种主流的编码语言，包括Java、C、C#、PHP和Javascript；

1.1. apidoc安装

apidoc利用npm来快速安装，进入Windows Shell，输入npm install apidoc -g进行apidoc的安装

1.2. 文档编写规则

只需要在java文件的方法上添加这些注解

/**

 * @apiGroup demo

 * @api {post} /api-post [第三方post接口调用]

 * @apiDescription 第三方post方法接口调用

 * @apiName api-post

 * @apiSuccess {JSONObject} jsonObject json对象.

 * @apiParam {String} [tokenKey]  token秘钥（必填）

 * @apiSampleRequest http://localhost:8080/RedseaPlatform/api-post

 * @apiParamExample {json} 入参-Example:

 * {

 * "tokenKey": asdfghjkl

 * }

 * @apiSuccessExample {json} 返回参数-Example:

 * {

 * "code": "0"

 * "msg" : ""

 * }

 *

 */

@api {method} path [title]



  只有使用@api标注的注释块才会在解析之后生成文档，title会被解析为导航菜单



(@apiGroup)下的小菜单

  method可以有空格，如{POST GET}



@apiGroup name

  分组名称，被解析为导航栏菜单



@apiName name

  接口名称，在同一个@apiGroup下，名称相同的@api通过@apiVersion区分，否者后面



@api会覆盖前面定义的@api



@apiDescription text

  接口描述，支持html语法



@apiVersion verison

  接口版本，major.minor.patch的形式



@apiIgnore [hint]

  apidoc会忽略使用@apiIgnore标注的接口，hint为描述



@apiSampleRequest url

  接口测试地址以供测试，发送请求时，@api method必须为POST/GET等其中一种



@apiDefine name [title] [description]

  定义一个注释块(不包含@api)，配合@apiUse使用可以引入注释块

  在@apiDefine内部不可以使用@apiUse



@apiUse name

  引入一个@apiDefine的注释块



@apiParam [(group)] [{type}] [field=defaultValue] [description]



@apiHeader [(group)] [{type}] [field=defaultValue]