nocobase2/packages/plugins/@nocobase/plugin-api-doc/README.zh-CN.md

80 lines
1.9 KiB
Markdown
Raw Normal View History

feat: api documentation plugin (#2255) * feat: api doc plugin * fix: merge * chore: upgrade swagger ui to latest * feat: get paths from recourser * feat: configure security * feat: add models * feat: reimplement resource action * feat: support render schemas correctly * feat: support load swagger documentation * refactor: implement `SwaggerManager` * fix: re import * feat: update info * refactor: do not use the cache strategy for the time being * feat: support collection builtin actions * fix: incorrect tag * feat: support different swagger json for different plugins * feat: support load server package * feat: support visit from plugin center * feat: add schemas for mapConfiguration * feat: update * fix: update tags * feat: support only render plugin that has swagger content * refactor: use swagger-ui-react instead of swagger-ui-dist * fix: clean * fix: reset * refactor: update plugin place * fix: revert * fix: remove version * fix: type error * feat: swagger doc * refactor: improve apis * feat: add doc * feat: support destination cache * fix: avoid authorization override * fix: auth bug * feat: update documentation * fix: typo * feat: support json * fix: key * fix: update yarn.lock * feat: update swagger doc * feat: swagger doc * docs: add auth swagger files (#2341) * docs: add auth swagger files * fix: yarn.lock * fix: skip core * feat: swagger doc * docs: improve auth docs * fix(theme-editor): avoid crashing * feat(theme-editor): improve api doc * docs: add localization-management swagger * docs(plugin-workflow): add api doc (#2379) * fix: remove files * fix: aaa * fix: dist * fix: load swagger * feat: acl api doc (#2494) * chore: acl api doc * feat: ui schema api doc * feat: multi apps api doc * chore: ui schema doc * feat: collection api doc * chore: association api doc * chore: single association doc * feat: move action doc * chore: list parameters * feat: update swagger doc * chore: collectionIndex to first * fix: test error * fix: ref * chore: doc tags * chore: template * chore: doc with association options * chore: single association doc * chore: relation type * chore: filter single association params * chore: m2m api doc * chore: params * fix: 0.12.0-alpha.5 * fix: update yarn.lock * chore: data wrap --------- Co-authored-by: chenos <chenlinxh@gmail.com> Co-authored-by: YANG QIA <2013xile@gmail.com> Co-authored-by: Rain <958414905@qq.com> Co-authored-by: Junyi <mytharcher@users.noreply.github.com> Co-authored-by: ChengLei Shao <chareice@live.com>
2023-08-24 00:27:57 +08:00
# api-doc
[English](./README.md) | 中文
## 简介
该插件基于 `swagger` 编写文档。
## 如何访问文档
1. 在插件中心访问地址是 `{domain}/admin/settings/api-doc/documentation`
2. 在插件中心外访问地址是 `{domain}/api-documentation`
## 如何编写 swagger 文档
> 插件内方式一样
1. `src/swagger.{ts,json}`
2. `src/swagger/index.{ts,json}`
上面的文件路径均可遍写文档,只需最后将您编写的文档默认导出即可,例子如下:
```ts
export default {
info: {
title: 'NocoBase API - Auth plugin',
},
tags: [],
paths: {},
components: {
schemas: {}
}
};
```
通常你只需要编写 **info.title**, **tags**, **paths**, **components** 即可其他内容如 **server**, **info** 的其他信息都合并我们的 **base-swagger**.
base swagger 包含如下代码
```ts
// base swagger
export default {
openapi: '3.0.3',
info: {
title: 'NocoBase API documentation',
description: '',
contact: {
url: 'https://github.com/nocobase/nocobase/issues',
},
license: {
name: 'Core packages are Apache 2.0 & Plugins packages are AGPL 3.0 licensed.',
url: 'https://github.com/nocobase/nocobase#license',
},
},
externalDocs: {
description: 'Find out more about NocoBase',
url: 'https://docs.nocobase.com/',
},
components: {
securitySchemes: {
'api-key': {
type: 'http',
scheme: 'bearer',
},
},
},
security: [
{
'api-key': [],
},
],
};
```
> 注意:涉及到运行时才能获取的配置,并没有填写在 base-swagger 里,如 server, version 字段
这些默认的配置你同样也可以覆盖它,在你编写插件的 `swagger` 文档时,你需要视你的插件文档是独立的文档,可以被单独访问。
详细的 `swagger` 编写规则请参考[官方文档](https://swagger.io/docs/specification/about/)