From 6eb763544e5064a4ac13febf88faba2c10e93606 Mon Sep 17 00:00:00 2001 From: Florian Date: Fri, 17 Jan 2025 22:59:33 +0800 Subject: [PATCH] docs: add api reference docs (#103) --- README-cn.md | 21 ++++++++---- README.md | 20 ++++++++--- docs/en-US/api-reference.md | 62 ++++++++++++++++++++++++++++++++++ docs/en-US/developer-manual.md | 8 +---- docs/zh-CN/api-reference.md | 62 ++++++++++++++++++++++++++++++++++ docs/zh-CN/developer-manual.md | 8 +---- 6 files changed, 156 insertions(+), 25 deletions(-) create mode 100644 docs/en-US/api-reference.md create mode 100644 docs/zh-CN/api-reference.md diff --git a/README-cn.md b/README-cn.md index c5bf21b..4f79cde 100644 --- a/README-cn.md +++ b/README-cn.md @@ -6,12 +6,13 @@ ![](docs/img/graphs.png) -> **OSGraph v2.0 新特性！！！** -> 1. 服务端重构完成，全面拥抱Python技术栈。 -> 2. 图谱支持多跳扩展，无限下钻洞察开源数据。 -> 3. 图谱支持`png`图片链接，一键嵌入Markdown。 -> 4. 更轻松的图谱扩展定制，直接打通生产服务。 - +> **OSGraph v2.0.0 新特性！！！** +> 1. 开源图谱支持参数化表单配置，使图谱可视化更加灵活。 +> 2. 服务端重构完成，全面拥抱Python技术栈。 +> 3. 图谱支持多跳扩展，无限下钻洞察开源数据。 +> 4. 图谱支持PNG图片链接，一键嵌入Markdown。 +> 5. 更轻松的图谱扩展定制，直接打通生产服务。 +> 6. 支持国际化。 ## 产品地址 @@ -19,6 +20,14 @@ 在这里你可以参考[图谱示例](docs/zh-CN/demo.md)进行产品体验。 +使用Markdown直接引用OSGraph图谱？试试： + +```markdown +![](https://osgraph.com/graphs/project-contribution/github/TuGraph-family/tugraph-db) +``` + +具体请参考：[OSGraph API设计规范](docs/zh-CN/api-reference.md) + ## 快速开始 diff --git a/README.md b/README.md index ba676c8..d04d1ca 100644 --- a/README.md +++ b/README.md @@ -6,11 +6,13 @@ ![](docs/img/graphs.png) -> **OSGraph v2.0 New Features !!!** -> 1. Backend service refactored completed, fully embracing the Python stack. -> 2. Support multi-hop graph expansion, enabling unlimited drill-down insights into open-source data. -> 3. Support `png` url of graph, enabling one-click embedding in Markdown. -> 4. Easier graph customization, directly connecting to production. +> **OSGraph v2.0.0 New Features !!!** +> 1. Open source graph supports parameterized form configuration, making graph visualization more flexible. +> 2. Backend service refactored completed, fully embracing the Python stack. +> 3. Support multi-hop graph expansion, enabling unlimited drill-down insights into open-source data. +> 4. Support PNG url of graph, enabling one-click embedding in Markdown. +> 5. Easier graph customization, directly connecting to production. +> 6. Internationalization support. ## Website @@ -18,6 +20,14 @@ You can refer to [Graph Demo](docs/en-US/demo.md) for product experience. +Want to directly embed OSGraph graphs in Markdown? Try: + +```markdown +![](https://osgraph.com/graphs/project-contribution/github/TuGraph-family/tugraph-db?lang=en-US) +``` + +For more details：[OSGraph API Reference](docs/en-US/api-reference.md) + ## QuickStart Startup and test on local machine: [Quick Start](docs/en-US/quick-start.md) diff --git a/docs/en-US/api-reference.md b/docs/en-US/api-reference.md new file mode 100644 index 0000000..a30f01c --- /dev/null +++ b/docs/en-US/api-reference.md @@ -0,0 +1,62 @@ +# OSGraph API Reference + +OSGraph provides unique URL identifiers for basic open source graphs, making it convenient for sharing, referencing, and modification, while also supporting Markdown embedding. + +Currently, the following open URLs are available: + +| Type | Function | Note | +|------------|------------------|---------------| +| **API** | Backend Integration | | +| **HTML** | Frontend Embedding | | +| **PNG** | Markdown Embedding | | +| **SVG** | Markdown Embedding | Coming Soon | + +## Design + +Open source graph URLs follow unified design specifications, distinguishing specific functions through URL prefixes. + +| Type | URL Prefix | Project URL Suffix | User URL Suffix | +|-----------|------------|----------------------------------------------|------------------------------------------| +| **API** | /api | /graphs/:graph/:platform/:org/:repo?:param* | /graphs/:graph/:platform/:user?:param* | +| **HTML** | - | /graphs/:graph/:platform/:org/:repo?:param* | /graphs/:graph/:platform/:user?:param* | +| **PNG** | /png | /graphs/:graph/:platform/:org/:repo?:param* | /graphs/:graph/:platform/:user?:param* | +| **SVG** | /svg | /graphs/:graph/:platform/:org/:repo?:param* | /graphs/:graph/:platform/:user?:param* | + +Taking the API URL as an example, its standardized format is: +![](../img/api-fmt.jpg) + +For example, TuGraph DB "Project Contribution" graph URL: +``` +https://osgraph.com/api/graphs/project-contribution/github/TuGraph-family/tugraph-db?lang=en-US&repo-limit=10&start-time=2015-01-17&end-time=2025-01-17 +``` + + +## Variables + +The specific meanings of variables in URLs are as follows: + +| Variable | Meaning | Note | +|------------|----------------------|---------------------------------------| +| `graph` | Graph Type | Currently supports 6 basic graph types | +| `platform` | Data Platform Source | Currently only supports `github` | +| `org` | Organization | | +| `repo` | Repository | | +| `user` | User | | +| `param` | Parameters | Parameter list relates to `graph` type | + +The supported parameter lists for different graph types are: + +| Graph Type | Meaning | `lang` | `start-time` | `end-time` | `repo-limit` | `user-limit` | `country-limit` | `company-limit` | `topic-limit` | +|---------------------|----------------------------|--------|--------------|------------|--------------|--------------|-----------------|-----------------|---------------| +| `project-contribution` | Project Contribution Graph | Y | Y | Y | Y | | | | | +| `project-ecosystem` | Project Ecosystem Graph | Y | - | - | Y | | | | | +| `project-community` | Project Community Graph | Y | - | - | | Y | Y | Y | | +| `developer-activity` | Developer Activity Graph | Y | - | - | | Y | | | | +| `os-partner` | OS Partner Graph | Y | - | - | | Y | | | | +| `os-interest` | OS Interest Graph | Y | - | - | Y | | | | Y | + +Note: +* `Y`: Supported +* `-`: To be supported +* Not supported by default + diff --git a/docs/en-US/developer-manual.md b/docs/en-US/developer-manual.md index 0823f7c..f6af11f 100644 --- a/docs/en-US/developer-manual.md +++ b/docs/en-US/developer-manual.md @@ -28,13 +28,7 @@ URLs in the interface layer follow standardized design principles, using consist | Page | /graphs/:graph/:platform/org/repo?:param* | | Image | /png/graphs/:graph/:platform/org/repo?:param* | -An example of the API's standardized format: -![](../img/api-fmt.jpg) - -For instance, the URL for the TuGraph DB "Project Contribution" graph: -``` -https://osgraph.com/api/graphs/project-contribution/github/TuGraph-family/tugraph-db?start-time=1&end-time=1733717926&repo-limit=10 -``` +For more details：[OSGraph API Reference](api-reference.md) #### 4.1.2 Adding New Graph Interfaces diff --git a/docs/zh-CN/api-reference.md b/docs/zh-CN/api-reference.md new file mode 100644 index 0000000..b0e8e78 --- /dev/null +++ b/docs/zh-CN/api-reference.md @@ -0,0 +1,62 @@ +# OSGraph API 文档 + +OSGraph为基础开源图谱提供了唯一URL标识，方便您的分享、引用和修改，同时支持了Markdown嵌入支持。 + +当前提供了以下开放URL供大家选择： + +| 类型 | 功能 | 备注 | +|----------|------------|------| +| **API** | 后端集成 | | +| **HTML** | 前端嵌入 | | +| **PNG** | Markdown嵌入 | | +| **SVG** | Markdown嵌入 | 即将支持 | + +## 设计规范 + +开源图谱URL采用统一的设计规范，通过URL前缀区分特定的功能。 + +| 类型 | URL前缀 | 项目类URL后缀 | 用户类URL后缀 | +|-----------|---------|----------------------------------------------|----------------------------------------| +| **API** | /api | /graphs/:graph/:platform/:org/:repo?:param* | /graphs/:graph/:platform/:user?:param* | +| **HTML** | - | /graphs/:graph/:platform/:org/:repo?:param* | /graphs/:graph/:platform/:user?:param* | +| **PNG** | /png | /graphs/:graph/:platform/:org/:repo?:param* | /graphs/:graph/:platform/:user?:param* | +| **SVG** | /svg | /graphs/:graph/:platform/:org/:repo?:param* | /graphs/:graph/:platform/:user?:param* | + +以API URL为例，其规范化格式为： +![](../img/api-fmt.jpg) + +如TuGraph DB “项目贡献”图谱URL： +``` +https://osgraph.com/api/graphs/project-contribution/github/TuGraph-family/tugraph-db?lang=en-US&repo-limit=10&start-time=2015-01-17&end-time=2025-01-17 +``` + +## 变量说明 + +URL中变量的具体含义如下： + +| 变量 | 含义 | 备注 | +|------------|--------|----------------| +| `graph` | 图谱类型 | 当前支持6种基础图谱类型 | +| `platform` | 数据平台来源 | 当前只支持`github` | +| `org` | 组织 | | +| `repo` | 仓库 | | +| `user` | 用户 | | +| `param` | 参数 | 参数列表和`graph`类型相关 | + + +不同的图谱类型，对应的参数列表支持为： + +| 图谱类型 | 含义 | `lang` | `start-time` | `end-time` | `repo-limit` | `user-limit` | `country-limit` | `company-limit` | `topic-limit` | +|--------------------|------|---|--------------|------------|--------------|--------------|-----------------|-----------------|---------------| +| `project-contribution` | 项目贡献图谱 | Y | Y | Y | Y | | | | | +| `project-ecosystem` | 项目生态图谱 | Y | - | - | Y | | | | | +| `project-community` | 项目社区图谱 | Y | - | - | | Y | Y | Y | | +| `developer-activity` | 开发活动图谱 | Y | - | - | | Y | | | | +| `os-partner` | 开源伙伴图谱 | Y | - | - | | Y | | | | +| `os-interest` | 开源兴趣图谱 | Y | - | - | Y | | | | Y | + +注： +* `Y`：已支持 +* `-`：待支持 +* 默认不支持 + diff --git a/docs/zh-CN/developer-manual.md b/docs/zh-CN/developer-manual.md index 09963fc..4179ce6 100644 --- a/docs/zh-CN/developer-manual.md +++ b/docs/zh-CN/developer-manual.md @@ -28,13 +28,7 @@ | 页面 | /graphs/:graph/:platform/org/repo?:param* | | 图片 | /png/graphs/:graph/:platform/org/repo?:param* | -如API的规范化格式为： -![](../img/api-fmt.jpg) - -如TuGraph DB “项目贡献”图谱URL： -``` -https://osgraph.com/api/graphs/project-contribution/github/TuGraph-family/tugraph-db?start-time=1&end-time=1733717926&repo-limit=10 -``` +具体请参考：[OSGraph API设计规范](api-reference.md) #### 4.1.2 新增图谱接口