nocobase2/packages/plugins/@nocobase/plugin-api-doc/README.zh-CN.md
jack zhang 705b7449f0
feat: new plugin manager, supports adding plugins through UI (#2430)
* refactor: plugin manager page

* fix: bug

* feat: addByNpm api

* fix: improve the addByNpm

* feat: improve applicationPlugins:list api

* fix: re-download npm package when restart app

* fix: plugin delete api

* feat: plugin detail api

* feat: zipUrl add api

* fix: upload api bug

* fix: plugin detail info

* feat: upgrade api

* fix: upload api

* feat: handle plugin load error

* feat: support authToken

* feat: muti lang

* fix: build error

* fix: self review

* Update plugin-manager.ts

* fix: bug

* fix: bug

* fix: bug

* fix: bug

* fix: bug

* fix: bugs

* fix: detail click and remove isOfficial

* fix: upgrade no refresh

* fix: file size and type check

* fix: bug

* fix: upgrade error

* fix: bug

* fix: bug

* fix: plugin card layout

* fix: handling exceptional cases

* fix: tgz file support

* fix: macos compress file

* fix: bug

* fix: bug

* fix: bug

* fix: bug

* fix: add upgrade npm type

* fix: bugs

* fix: bug

* fix: change plugins static expose url

* fix: api prefix

* fix: bug

* fix: add nginx `/static/plugin/` path

* fix: bugs and pr docker build no dts

* fix: bug

* fix: build tools bug

* fix: improve code

* fix: build bug

* feat: improve plugin info

* fix: ui bug

* fix: plugin document bug

* feat: improve code

* feat: improve code

* feat: process dev deps check

* feat: improve code

* feat: process.env.IS_DEV_CMD

* fix: do not delete the plugin package

* feat: plugin symlink

* fix: tsx watch --ignore=./storage/plugins/**

* fix: test error

* fix: improve code

* fix: improve code

* fix: emitStartedEvent

* fix: improve code

* fix: type error

* fix: test error

* test: console.log

* fix: createStoragePluginSymLink

* fix: clientStaticMiddleware rename to clientStaticUtils

* feat: build tools support plugins folder

* fix: 350px

* fix: error

* feat: client dev support plugin folder

* fix: clear cli options

* fix: typeError: Converting circular structure to JSON

* fix: plugin name

* chore: restart application after command

* feat: upgrade error & docs

* Update v14-changelog.md

* Update v14-changelog.md

* Update v14-changelog.md

* fix: gateway test

* refactor(plugin-workflow): add ready state for gracefully tearing down

* Revert "chore: restart application after command"

This reverts commit 5015274f8e4e06e506e15754b672330330e8c7f8.

* chore: stop application whe restart

* T 1218 change plugin folder (#2629)

* feat: change folder name

* feat: change `pm create` command

* feat:  revert plugin name change

* fix: delete samples

* feat: change plugins folder

* fix: pm create

* feat: update docs

* fix: link package error

* fix: docs

* fix: create command

* fix: pm add error

* fix: create  add build

* fix: pm creatre + add

* feat: add tar command

* fix: docs

* fix: bug

* fix: docs

---------

Co-authored-by: chenos <chenlinxh@gmail.com>

* feat: docs

* Update your-fisrt-plugin.md

* Update your-fisrt-plugin.md

* chore: application reload

* chore: test

* fix: pm add error

* chore: preset install skip exists plugin

* fix: createIfNotExists

---------

Co-authored-by: chenos <chenlinxh@gmail.com>
Co-authored-by: chareice <chareice@live.com>
Co-authored-by: Zhou <zhou.working@gmail.com>
Co-authored-by: mytharcher <mytharcher@gmail.com>
2023-09-12 22:39:23 +08:00

80 lines
1.9 KiB
Markdown

# 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/)