sealday
ede7ead8b1
Co-authored-by: sealday <sealday@gmail.com> Reviewed-on: daoyoucloud/tachybase#1045
77 lines
1.9 KiB
Markdown
77 lines
1.9 KiB
Markdown
# api-doc
|
|
|
|
English | [中文](./README.zh-CN.md)
|
|
|
|
|
|
## Introduction
|
|
|
|
This plugin is based on `swagger` to write documentation.
|
|
|
|
## How to access the documentation
|
|
|
|
1. The access address in the plugin center is `{domain}/admin/settings/api-doc/documentation`
|
|
2. The access address outside the plugin center is `{domain}/api-documentation`
|
|
|
|
## How to write swagger documentation
|
|
|
|
> The method in the plugin is the same
|
|
|
|
1. `src/swagger.{ts,json}`
|
|
2. `src/swagger/index.{ts,json}`
|
|
|
|
The file paths above can all be traversed to write documentation. Just export your written documentation by default. An example is shown below:
|
|
|
|
```ts
|
|
export default {
|
|
info: {
|
|
title: 'TachyBase API - Api-doc plugin',
|
|
},
|
|
tags: [],
|
|
paths: {},
|
|
components: {
|
|
schemas: {}
|
|
}
|
|
};
|
|
```
|
|
|
|
Usually, you only need to write **info.title**, **tags**, **paths**, and **components**. Other information such as **server** and **info** are merged into our **base-swagger**.
|
|
|
|
Base swagger includes the following code:
|
|
|
|
```ts
|
|
// base swagger
|
|
export default {
|
|
openapi: '3.0.3',
|
|
info: {
|
|
title: 'TachyBase API documentation',
|
|
description: '',
|
|
contact: {
|
|
url: 'https://github.com/tachybase/tachybase/issues',
|
|
},
|
|
license: {
|
|
name: 'All packages are Apache 2.0 licensed.',
|
|
url: 'https://github.com/tachybase/tachybase#license',
|
|
},
|
|
},
|
|
components: {
|
|
securitySchemes: {
|
|
'api-key': {
|
|
type: 'http',
|
|
scheme: 'bearer',
|
|
},
|
|
},
|
|
},
|
|
security: [
|
|
{
|
|
'api-key': [],
|
|
},
|
|
],
|
|
};
|
|
```
|
|
|
|
> Note that configurations that can only be obtained at runtime, such as the server and version fields, are not filled in the base-swagger.
|
|
|
|
You can also override these defaults. When writing the swagger documentation for your plugin, you should consider whether your plugin's documentation can be accessed independently.
|
|
|
|
For detailed swagger writing rules, please refer to the [official documentation](https://swagger.io/docs/specification/about/).
|