mirror of
https://github.com/fastapi-admin/fastapi-admin.git
synced 2026-03-13 10:32:25 +08:00
381 lines
9.2 KiB
Markdown
381 lines
9.2 KiB
Markdown
# REST-ADMIN [中文文档](./README-zh.md)
|
||
|
||
> An Powerful Admin Dashboard based on [Boostrap-Vue](https://github.com/bootstrap-vue/bootstrap-vue/).
|
||
|
||
Demo: http://rest-admin.genyii.com/ `admin admin`
|
||
|
||
Please support me on https://afdian.net/@johnny if you like it.
|
||
如果觉得有用请在爱发电上赞助我：https://afdian.net/@johnny
|
||
|
||
## Features
|
||
|
||
- **Bootswatch Themes**
|
||
- Powerful **Data Table** with sorting, pagination, searching, display images...
|
||
- Powerful **Edit Form Builder** can display/edit any value of text, image, boolean...
|
||
- Fully support for Resource-based CRUD option.
|
||
- English based fully i18n support.
|
||
- **Highly Configurable** site info. Such as: site name, logo, **Menu** and footer...
|
||
- Production ready. It has been used in two projects in our company.
|
||
|
||
## Screenshots
|
||
|
||
| - | - |
|
||
| --------------------------------------------------------------------------------------- | ------------------------------------------- |
|
||
|  Login Page |  Home page |
|
||
|  Data Table for posts |  Data Form for post |
|
||
|  Wechat Group (Search Wechat `johnny77577` to join in) |  Free Videos |
|
||
|
||
## Quick Start
|
||
|
||
```bash
|
||
git clone git@github.com:wxs77577/rest-admin.git
|
||
cd rest-admin
|
||
code . # open with vscode [optional]
|
||
npm i # or cnpm i
|
||
|
||
# start with local test api server
|
||
npm run test-api # start test api server
|
||
npm run serve # start rest admin client
|
||
```
|
||
|
||
> The default username and password of test-api is `admin` and `admin`
|
||
|
||
### Build
|
||
|
||
```bash
|
||
API_URI=http://localhost:5555/admin/api/ npm run build
|
||
```
|
||
|
||
Then just copy `/dist/admin` folder to the anywhere.
|
||
|
||
> There is a built-in restful api based on `express` for test.
|
||
|
||
## Fields Definition
|
||
|
||
> Used in listing tables and editing forms
|
||
> Default PRIMARY_KEY field is `_id`, feel free to change it in `/src/config.json`
|
||
|
||
Example:
|
||
|
||
```javascript
|
||
{
|
||
"_id": { "label": "ID" },
|
||
"title": { "label": "Title" },
|
||
"type": {
|
||
"label": "Type",
|
||
"type": "select",
|
||
"options": [
|
||
{ "text": "Vue", "value": "vue" },
|
||
{ "text": "React", "value": "react" },
|
||
{ "text": "Angular", "value": "angular" }
|
||
]
|
||
},
|
||
"body": { "type": "html", "group": "Detail" },
|
||
"steps": {
|
||
"type": "array",
|
||
"group": "Steps",
|
||
"fields": {
|
||
"name": { "label": "Name" },
|
||
"date": { "label": "date" }
|
||
}
|
||
},
|
||
|
||
"_actions": {
|
||
// define table view, it's optional.
|
||
"buttons": {
|
||
// define buttons as `false` to hide in actions colum
|
||
"delete": false,
|
||
"edit": false
|
||
},
|
||
"toolbar": {
|
||
// define actions in top toolbar table view
|
||
"extra": [
|
||
// add extra buttons
|
||
{ "to": "/form?uri=vouchers/generate", "label": "Generate Vouchers" } //properties of `<b-button>`
|
||
]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### Field properties
|
||
|
||
- `label` Title for display
|
||
- `cols` column width, total is 12.
|
||
- `input_cols` column width of input control.
|
||
- `group` title for tabs in create/edit forms
|
||
- `type` Field type, accepted values and additional properties for some fields.
|
||
- `select` raw html `<select>` tag from [b-select](https://bootstrap-vue.js.org/docs/components/form-select) of `bootstrap-vue`
|
||
- `options` e.g. `[{ "text": "Label", "value": "1" }]`
|
||
- `select2` [vue-select](https://github.com/sagalbot/vue-select), like `select2` in jQuery
|
||
- `options` e.g. `[{ "text": "Label", "value": "1" }]`
|
||
- `tree` [vue-treeselect](https://vue-treeselect.js.org/)
|
||
- `options` **use `text` and `value` instead `label` and `id`** e.g. `[{ "text": "Label", "value": "1", "children": [ { "text": "Item1", "value": "2" } ] }]`
|
||
- `date` [vue2-datepicker](https://github.com/mengxiong10/vue2-datepicker) supports **date range**
|
||
- `switch` A iOS-liked switch component
|
||
- `html` An WYSIWYG html editor from [vue-html5-editor](https://github.com/PeakTai/vue-html5-editor)
|
||
- `array` Array values
|
||
- `fields` child fields defination
|
||
- `is_table` display as a table ?
|
||
- `radiolist`
|
||
- `options` e.g. `[{ "text": "Label", "value": "1" }]`
|
||
- `checkboxlist`
|
||
- `options` e.g. `[{ "text": "Label", "value": "1" }]`
|
||
- `checkbox`
|
||
- `file` File uploader
|
||
- `limit` define file limit options of **size** in byets, e.g. `{ size: 1000000 }`
|
||
- `image` Image file uploader with preview.
|
||
- `limit` define file limit options of **width** **height** and **size** in byets, e.g. `{ "width": 320, "height": 180, size: 1000000 }`
|
||
- `audio` like `image`
|
||
- `limit` define file limit options of **size** in byets, e.g. `{ size: 1000000 }`
|
||
- `video` like `image`
|
||
- `limit` define file limit options of **size** in byets, e.g. `{ size: 1000000 }`
|
||
- `textarea`
|
||
- `number`
|
||
- `text`
|
||
- `required`
|
||
- Any other properties accepted in https://bootstrap-vue.js.org/docs/components/form-input, please notice that every kind of field component has it's own properties.
|
||
|
||
## APIs
|
||
|
||
> Tips: check `/api/index.js` :p
|
||
|
||
Example Base Api Url: http://localhost:8088/admin/api
|
||
|
||
#### GET `/site` (url: http://localhost:8088/admin/api/site)
|
||
|
||
Get config data of site
|
||
|
||
- Returns
|
||
```javascript
|
||
{
|
||
"name": "Site Name",
|
||
"logo": "http://.../logo.png",
|
||
"locale": "en-US", //or zh-CN
|
||
"locale_switcher": false, //hide locale switcher
|
||
"menu": [
|
||
{
|
||
"name": "Home",
|
||
"url": "/",
|
||
"icon": "fa fa-home"
|
||
// for home page
|
||
},
|
||
{
|
||
"name": "Content",
|
||
"title": true
|
||
// display as a delimiter
|
||
},
|
||
{
|
||
"name": "Posts",
|
||
"url": "/rest/posts",
|
||
"icon": "fa fa-list"
|
||
// url format of resource list: /rest/:resourceName
|
||
},
|
||
{
|
||
"name": "Config",
|
||
"url": "/form?uri=site/settings",
|
||
"icon": "fa fa-cogs"
|
||
// a custom form.
|
||
},
|
||
{
|
||
"name": "Logout",
|
||
"url": "/login",
|
||
"icon": "fa fa-lock"
|
||
// for logout
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### POST `/login`
|
||
|
||
For admin user login
|
||
|
||
- POST DATA
|
||
```javascript
|
||
{
|
||
"username": "admin",
|
||
"password": "admin"
|
||
}
|
||
```
|
||
- Returns
|
||
```javascript
|
||
{
|
||
"user": {
|
||
"username": "admin",
|
||
...
|
||
},
|
||
"token": "1o2u3h4oi2u3h4jkashdflsda"
|
||
}
|
||
```
|
||
or with validation errors
|
||
> must response `422` http status.
|
||
```javascript
|
||
{
|
||
"name": "HttpException",
|
||
"message": [{ "field": "password", "message": "Incorrect password." }]
|
||
}
|
||
```
|
||
|
||
#### GET `/:resource`
|
||
|
||
Fetch all records of a resource.
|
||
`:resource` means any resource name. e.g. `/users`, `/posts`...
|
||
|
||
- Returns **IMPORTANT**
|
||
```javascript
|
||
{
|
||
"total": 80,
|
||
"perPage": 10,
|
||
"page": 1,
|
||
"data": [
|
||
{...},
|
||
{...},
|
||
{...},
|
||
]
|
||
}
|
||
```
|
||
|
||
#### GET `/:resource/grid`
|
||
|
||
Fetch grid view config of a resource.
|
||
`:resource` means any resource name. e.g. `/users/grid`, `/posts/grid`...
|
||
|
||
- Returns **IMPORTANT**
|
||
```javascript
|
||
{
|
||
"searchModel": {},
|
||
"searchFields": {
|
||
render a searching form
|
||
...see Fields Definition...
|
||
},
|
||
"fields": {
|
||
render a table view
|
||
...see Fields Definition...
|
||
}
|
||
}
|
||
```
|
||
|
||
#### GET `/:resource/form`
|
||
|
||
Fetch editing form config of a resource.
|
||
`:resource` means any resource name. e.g. `/users/form`, `/posts/form`...
|
||
|
||
- Returns **IMPORTANT**
|
||
```javascript
|
||
{
|
||
"model": {},
|
||
"fields": {
|
||
render a editing form
|
||
...see Fields Definition...
|
||
}
|
||
}
|
||
```
|
||
|
||
#### POST `/:resource`
|
||
|
||
create a resource
|
||
|
||
- POST DATA
|
||
```javascript
|
||
{
|
||
"_id": "12341234",
|
||
"title": "The New Title",
|
||
...
|
||
}
|
||
```
|
||
- Returns
|
||
```javascript
|
||
{
|
||
"_id": "12341234",
|
||
"title": "The New Title",
|
||
...
|
||
}
|
||
```
|
||
|
||
#### PUT `/:resource/:id`
|
||
|
||
update a resource
|
||
|
||
- POST DATA (Request Payload)
|
||
```javascript
|
||
{
|
||
"_id": "12341234",
|
||
"title": "The New Title",
|
||
...
|
||
}
|
||
```
|
||
- Returns
|
||
```javascript
|
||
{
|
||
"_id": "12341234",
|
||
"title": "The New Title",
|
||
...
|
||
}
|
||
```
|
||
|
||
#### DELETE `/:resource/:id`
|
||
|
||
delete a resource
|
||
|
||
- Returns
|
||
```javascript
|
||
{
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
#### DELETE `/:resource`
|
||
|
||
delete all
|
||
|
||
- Returns
|
||
```javascript
|
||
{
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
#### Custom Form ?
|
||
|
||
> To render a custom form, you need to define a `menu` item in `/site` api, or add an `extra` button of toolbar in `/:resource/grid`.
|
||
|
||
There are two apis for a custom form:
|
||
|
||
1. Get form definition
|
||
|
||
- GET `/site/settings`
|
||
- Returns
|
||
```
|
||
{
|
||
"title": "Form Title",
|
||
"fields": {
|
||
...see Fields Definition...
|
||
}
|
||
}
|
||
```
|
||
|
||
2. Handle submission
|
||
|
||
- POST `/site/settings`
|
||
- Returns
|
||
```javascript
|
||
{
|
||
"success": true,
|
||
"message": "Well done!", //[optional] will show after form submited.
|
||
"redirect": "/" //[optional] auto redirect after form submited, default is back to the last page.
|
||
}
|
||
```
|
||
|
||
## i18n
|
||
|
||
> Check [vu-i18n](https://github.com/kazupon/vue-i18n/) for detailed documentation.
|
||
|
||
REST-ADMIN gives built-in support for `en-US` and `zh-CN`, you can change translation files in `/src/i18n/*.json`.
|
||
|
||
## Thanks to
|
||
|
||
- Vue.js and Bootstrap v4 based [bootstrap-vue](https://github.com/bootstrap-vue/bootstrap-vue)
|
||
- Nice UI from [Core UI](https://coreui.io/)
|
||
- i18n component from [vue-i18n](https://github.com/kazupon/vue-i18n/)
|