开放 API 与 Webhook
  1. 个人访问令牌
  2. WebHook
文件管理与 Wiki
  1. 项目文件管理
  2. 项目 Wiki

接入自动化工具

「CODING API 文档」目前支持接入 Docker 与 cURL 进行自动化发布文档,省去了人工上传 API 数据的时间和繁琐的步骤。

即将支持接入「CODING 持续集成」与 Jenkins 。

准备工作

因为接入自动化工具需要用到「CODING 开放 API」的能力,而后者需要授权才可访问,所以需要您先开通“项目访问令牌(推荐)”或者“个人访问令牌”。

为了区分人工和自动化的操作,建议使用项目访问令牌,并为 API 文档开通专用访问令牌。

开通项目访问令牌

点击【项目】→【设置】→【开发者选项】→【项目令牌】,选择【新建项目令牌】,依次填入信息。其中管理权限请勾选【API 文档】。

获取令牌用户名和密码

在【项目令牌】页面,点击【查看密码】,可获取令牌用户名和密码。

我们要用到的是【令牌密码(token)】,复制后备用。

准备好符合规范的 API 数据

「CODING API 文档」目前支持符合 OpenAPI / Postman / apiDoc 这 3 种规范下的 YAML 或者 JSON 格式的 API 数据。

比如,这是 OpenAPI 规范下 YAML 格式的 API 数据:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
openapi: 3.0.0
info:
title: Sample API
description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
version: 0.1.9
servers:
- url: http://api.example.com/v1
description: Optional server description, e.g. Main (production) server
- url: http://staging-api.example.com
description: Optional server description, e.g. Internal staging server for testing
paths:
/users:
get:
summary: Returns a list of users.
description: Optional extended description in CommonMark or HTML.
responses:
'200': # status code
description: A JSON array of user names
content:
application/json:
schema:
type: array
items:
type: string

使用 Docker 接入自动化

Docker 是一种轻量级的虚拟化技术,是一种 Linux 容器(Linux Containers,缩写为 LXC)技术的封装。

为了更方便地上传 API 数据,CODING 专门提供了 Docker 镜像【apidoc-publisher】来实现 API 数据的上传,相较于 cURL 方式更加易懂,操作更加方便。

环境变量

环境变量 描述
ACCESS_TOKEN {访问令牌}
APIDOC_TEAM 企业域名,若企业首页地址为:https://abc.coding.net, 则企业域名即为 abc
APIDOC_PROJECT 项目地址名称,若项目首页地址为:https://abc.coding.net/p/xyz, 则项目地址名称即为 xyz
APIDOC_ID API 文档资源 ID,若选中文档详情地址为:https://abc.coding.net/p/xyz/api-docs/1, 则 ID 即为 1
APIDOC_RELEASE_TYPE 传输内容形式:content 为文本形式,file 上传文件形式
APIDOC_CONTENT {API 数据内容}

上传发布 API 文档

Docker 方式支持“文本”和“上传文件”这 2 种形式发布 API 文档,我们更推荐使用“上传文件”形式。

上传文件形式发布

上传文件形式需要指定 APIDOC_RELEASE_TYPE 为 file,并挂载 API 数据文件的目录至容器的 /opt 目录中,其中 API 数据必须保存在名为 data.txt 的文件中。

请将以下命令中的环境变量替换为您的真实数据,无需保留花括号,并在终端内执行:

1
2
3
4
5
6
7
8
docker run -it --rm \
-e ACCESS_TOKEN={访问令牌} \
-e APIDOC_TEAM={企业域名} \
-e APIDOC_PROJECT={项目地址名称} \
-e APIDOC_ID={API 文档资源 ID} \
-e APIDOC_RELEASE_TYPE=file \
-v {API 数据文件路径}/data.txt:/opt/data.txt \
ecoding/apidoc-publisher

比如我的命令是这样的:

1
2
3
4
5
6
7
8
docker run -it --rm \
-e ACCESS_TOKEN=token \
-e APIDOC_TEAM=codingcorp \
-e APIDOC_PROJECT=code-repo \
-e APIDOC_ID=2 \
-e APIDOC_RELEASE_TYPE=file \
-v /c/Workspace/code-repo/data.txt:/opt/data.txt \
ecoding/apidoc-publisher

这是我的操作演示截图,终端返回api doc success即为发布成功:

在文档管理页面可以看到更新动态:

文本形式发布

文本形式需要指定 APIDOC_RELEASE_TYPE 为 content,并在命令中传入 API 数据内容,其中 API 数据要以单引号括起来。

请将以下命令中的环境变量替换为您的真实数据,无需保留花括号,并在终端内执行:

1
2
3
4
5
6
7
8
docker run -it --rm \
-e ACCESS_TOKEN={访问令牌} \
-e APIDOC_TEAM={企业域名} \
-e APIDOC_PROJECT={项目地址名称} \
-e APIDOC_ID={API 文档资源 ID} \
-e APIDOC_RELEASE_TYPE=content \
-e APIDOC_CONTENT='{API 数据内容}' \
ecoding/apidoc-publisher

比如我的命令是这样的:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
docker run -it --rm \
-e ACCESS_TOKEN=token \
-e APIDOC_TEAM=codingcorp \
-e APIDOC_PROJECT=code-repo \
-e APIDOC_ID=2 \
-e APIDOC_RELEASE_TYPE=content \
-e APIDOC_CONTENT='openapi: 3.0.0
info:
title: Sample API
description: Optional multiline or single-line description in [CommonMark](http://commonmark.org/help/) or HTML.
version: 0.1.9
servers:
- url: http://api.example.com/v1' \
ecoding/apidoc-publisher

这是我的操作演示截图:

使用 cURL 接入自动化

*cURL *是一个利用URL语法在命令行下工作的文件传输工具,它支持文件上传和下载,所以是综合传输工具。

使用 cURL 工具可以很简单的在命令行模式下将 API 数据上传至 CODING,这在 CI / CD 工具中非常实用。

「CODING API 文档」提供了 API 发布的接口,可以上传 API 数据更新 API 文档,支持文件上传或以文本形式传输 API 数据。

接口地址:

1
POST https://{:team}.coding.net/api-docs/api/v1/projects/{:project}/api-docs/{:id}/release

路由参数

接口中的路由参数将以 : 开头标识,如 {:team}

参数 描述
:team 企业域名,若企业首页地址:https://abc.coding.net, 则企业域名即为 abc
:project 项目地址名称,若项目首页地址:https://abc.coding.net/p/xyz, 则项目地址名称即为 xyz
:id API 文档资源 ID,若选中文档详情地址为:https://abc.coding.net/p/xyz/api-docs/1, 则 ID 即为 1
参数 描述
Authorization 授权信息,此处填写访问令牌,格式为:token {访问令牌}
请求参数 / Body
  • 文本形式

    可直接将 API 数据内容字符串传给服务端。
    API 数据内容支持 OpenAPI、Postman、Apidoc,格式支持 JSON、YAML

    参数 描述
    content API 数据内容,如 OpenAPI 描述文件内容

    范例:

    1
    2
    curl -X POST -H "Authorization: token {访问令牌}" -H "Accept:application/json" https://abc.coding.net/api-docs/open/api/v1/projects/xyz/docs/2/releases \
    -F "content={API 数据内容}"
  • 上传文件

    可将生成的 API 数据文件直接上传至服务端,支持内容及格式与文本形式一致。

    参数 描述 支持格式 最大文件大小
    file API 数据文件路径,如:/data/api_data.yml yml / json 5MB

    范例:

    1
    2
    curl -X POST -H "Authorization: token {访问令牌}" -H "Accept:application/json" https://abc.coding.net/api-docs/open/api/v1/projects/xyz/docs/2/releases \
    -F "filename=@{API 数据文件路径}"
上一篇API 文档管理
文档是否对您有用?
感谢反馈有用
感谢反馈没用