其他分享
首页 > 其他分享> > APISIX Dashboard中文文档(一)

APISIX Dashboard中文文档(一)

作者:互联网

2022年7月6日13:24:56

官方文档:https://apisix.apache.org/zh/docs/dashboard/USER_GUIDE/

用户指南

以下是模块快照的一部分。

仪表板#
我们通过在 iframe 中引用来支持监控页面。 在访问 Grafana 之前,请启用 allow_embedding=true,默认为 false。 由于安全策略,这会导致浏览器无法正确呈现 Grafana 页面。

image

路由#
Route 模块旨在通过 UI 控制路由,而不是调用 API。

列表#
image

创建#
image

image

image

image

image

设置#
image

导入 OpenAPI 指南

概述#
OpenAPI 规范 (OAS) 为 RESTful API 定义了一个与语言无关的标准接口,它允许人类和计算机在不访问源代码、文档或通过网络流量检查的情况下发现和理解服务的功能。

Apache APISIX Dashboard 支持导入OpenApi3.0(我们将简称为 OAS3.0)文件,json并且yaml都支持,以创建一个或多个路由。目前我们支持大部分的 OpenApi 规范,但还是有一些区别,比如兼容性和扩展字段。

扩展字段#
APISIX Route 中有些字段是必填的,但 OAS3.0 的属性中没有包含,为了方便基于 OAS3.0 扩展自定义路由实体,我们增加了一些扩展字段,如上游、插件、主机等上。所有扩展都以 x-apisix 开头。

Extended fields APISIX Route Properties
x-apisix-plugins plugins
x-apisix-script script
x-apisix-upstream upstream
x-apisix-host host
x-apisix-hosts hosts
x-apisix-remote_addr remote_addr
x-apisix-priority priority
x-apisix-vars vars
x-apisix-filter_func filter_func
x-apisix-labels labels
x-apisix-enable_websocket enable_websocket
x-apisix-status status
x-apisix-service_id service_id
x-apisix-upstream_id upstream_id

请注意,我们只扩展了第一级字段,子级字段仍然保持不变。 以 x-apisix-upstream 为例。

...
# 我们在 OAS3.0 中添加 x-apisix-upstream 作为扩展字段代表上游
x-apisix-upstream:
  # x-apisix-upstream 的子字段仍然与上游的子字段保持一致
  type: roundrobin
  nodes:
    - host: 172.16.238.20
      port: 1980
      weight: 1
...

有关 APISIX 路由属性的更多详细信息,请参阅

OAS3.0 兼容性

当我们从 OAS3.0 导入路由时,会因为 APISIX 的 Route 中没有对应的字段而遗漏 OAS3.0 中的一些字段:

  1. API General Info:用于描述你的API的一般信息,有时,一个OAS3.0文件包含一系列 属于应用程序的 api,因此此信息不同于 api 的名称和额外的基本信息。

例子:

# this part of information will be missed
openapi: 3.0.0
info:
  version: 1.0.0-oas3
  description: test desc
  license:
    name: Apache License 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0'
  title: test title
...
  1. API 服务器和基本路径:上游 url + url 前缀(选项)

例子:

# this part of information will be missed
...
servers:
  - url: https://api.example.com/v1
...
  1. Path params: 路径中描述的 api 参数.

例子:

# 不管 uri 中有多少路径参数
# 从 OAS3.0 文件导入路由后,我们将得到带有 uri 的路由,如 `/get/*`
...
paths:
  /get/{id}/{name}:
    delete:
      operationId: api1DELETE
...
  1. Query params: 查询中描述的 api 参数.

Example:

...
paths:
  /users:
    get:
      summary: Get a user by ID
      # this part of information will be missed
      parameters:
        - in: path
          name: userId
          schema:
            type: integer
          required: true
          description: Numeric ID of the user to get
...
  1. Responses description and links: 定义 API 操作的响应.

Example:

...
paths:
  /hello:
    get:
      description: hello world.
      operationId: hello
      x-apisix-service_id: service1
      # this part of information will be missed
      responses:
        '200':
          description: list response
        default:
          description: unexpected error
...

不同用户场景下OAS3.0配置示例

配置基本发布路由

提示:导入的路由默认的status为unpublished,表示该路由不能访问,如果要导入一个published的路由,需要在里面加上x-apisix-status: 1 你的OAS3.0文件

openapi: 3.0.0
info:
  version: 1.0.0-oas3
  description: test desc
  license:
    name: Apache License 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0'
  title: test title
paths:
  /hello: # route uri
    get: # route method
      description: hello world. # route desc
      operationId: hello # route name
      x-apisix-upstream: # route upstream
        type: roundrobin
        nodes:
          - host: 172.16.238.20
            port: 1980
            weight: 1
      x-apisix-status: 1 # the route will be published after imported
      responses:
        '200':
          description: list response
        default:
          description: unexpected error

使用插件配置路由

提示:扩展字段支持的大多数插件 x-apisix-plugins

openapi: 3.0.0
info:
  version: 1.0.0-oas3
  description: test desc
  license:
    name: Apache License 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0'
  title: test title
paths:
  /hello:
    get:
      description: hello world.
      operationId: hello
      x-apisix-upstream:
        type: roundrobin
        nodes:
          - host: 172.16.238.20
            port: 1980
            weight: 1
      x-apisix-plugins:
        limit-count:
          count: 2
          time_window: 60
          rejected_code: 503
          key: remote_addr
          policy: local
      responses:
        '200':
          description: list response
        default:
          description: unexpected error

配置带有参数验证的路由

提示:对于插件 request-validation,我们将使用 参数序列化 用于标头参数验证和 描述请求正文 用于 OAS3.0 中的正文参数验证

openapi: 3.0.0
info:
  version: "1"
  description: |-
    test desc
  license:
    name: Apache License 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0
  title: |-
    test title
paths:
  /hello:
    post:
      description: |-
        hello world.
      operationId: hello
      x-apisix-upstream:
        type: roundrobin
        nodes:
          - host: "172.16.238.20"
            port: 1980
            weight: 1
      parameters:
        - name: id
          in: header
          description: ID of pet to use
          required: true
          schema:
            type: string
          style: simple

      requestBody:
        content:
          'application/x-www-form-urlencoded':
            schema:
              properties:
                name:
                  description: Update pet's name
                  type: string
                status:
                  description: Updated status of the pet
                  type: string
              required:
                - status
      responses:
        200:
          description: list response
        default:
          description: unexpected error

使用身份验证插件配置路由

注意: 对于插件 basic-auth jwt-authkey-auth 我们将使用 Authentication 在 OAS3.0

components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
openapi: 3.0.0
info:
  version: "1"
  description: |-
    test desc
  license:
    name: Apache License 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0
  title: |-
    test title
paths:
  /hello:
    post:
      description: |-
        hello world.
      operationId: hello
      x-apisix-upstream:
        type: roundrobin
        nodes:
          - host: "172.16.238.20"
            port: 1980
            weight: 1
      security:
        - basicAuth: []
        - ApiKeyAuth: []
        - BearerAuth: []
      responses:
        200:
          description: list response
        default:
          description: unexpected error

配置现有服务或上游的路由

提示: 如果 APISIX 中不存在 service_idupstream_id,从配置文件导入路由会报错

openapi: 3.0.0
info:
  version: 1.0.0-oas3
  description: test desc
  license:
    name: Apache License 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0'
  title: test title
paths:
  /hello:
    get:
      description: hello world.
      operationId: hello
      x-apisix-service_id: service1
      responses:
        '200':
          description: list response
        default:
          description: unexpected error

配置多个路由

info:
  title: RoutesExport
  version: 3.0.0
openapi: 3.0.0
paths:
  /get:
    delete:
      operationId: api1Delete
      requestBody: {}
      responses:
        default:
          description: ''
      x-apisix-enableWebsocket: false
      x-apisix-labels:
        API_VERSION: v2
        dev: test
      x-apisix-plugins:
        proxy-rewrite:
          disable: false
          scheme: https
      x-apisix-priority: 0
      x-apisix-status: 1
      x-apisix-upstream:
        nodes:
          - host: httpbin.org
            port: 443
            weight: 1
        type: roundrobin
        pass_host: node
      x-apisix-vars: []
    get:
      operationId: api1Get
      requestBody: {}
      responses:
        default:
          description: ''
      x-apisix-enableWebsocket: false
      x-apisix-labels:
        API_VERSION: v2
        dev: test
      x-apisix-plugins:
        proxy-rewrite:
          disable: false
          scheme: https
      x-apisix-priority: 0
      x-apisix-status: 1
      x-apisix-upstream:
        nodes:
          - host: httpbin.org
            port: 443
            weight: 1
        type: roundrobin
        pass_host: node
      x-apisix-vars: []
  /post:
    post:
      operationId: test_post
      requestBody: {}
      responses:
        default:
          description: ''
      security: []
      x-apisix-enableWebsocket: false
      x-apisix-labels:
        API_VERSION: v1
        version: v1
      x-apisix-plugins:
        proxy-rewrite:
          disable: false
          scheme: https
      x-apisix-priority: 0
      x-apisix-status: 1
      x-apisix-upstream:
        nodes:
          - host: httpbin.org
            port: 443
            weight: 1
        type: roundrobin
        pass_host: node
      x-apisix-vars: []

管理API 的 API 文档

Manager API 直接操作 ETCD 并为 Apache APISIX 提供数据管理,为前端或其他客户端提供 API.

License: Apache License 2.0

/apisix/admin/migrate/export

GET

简介

导出配置文件以进行迁移

参数

None.

返回

A file for download.

/apisix/admin/migrate/import

简介

导入配置文件以恢复配置

POST

参数 (FORM)
Name Located in Description Required Schema
mode body(form) import mode (return, skip or overwrite) Yes string
file body(form) file to upload Yes string
返回
Code Description Schema
0 import success ApiError
20001 Config conflict ApiError

/apisix/admin/check_ssl_cert

POST

简介

验证 SSL 证书和密钥

参数
Name Located in Description Required Schema
cert body cert of SSL Yes string
key body key of SSL Yes string
返回
Code Description Schema
0 SSL verify passed ApiError
default unexpected error ApiError

/apisix/admin/check_ssl_exists

POST

简介

检查 SSL 是否存在

参数
Name Located in Description Required Schema
cert body cert of SSL Yes string
key body key of SSL Yes string
返回
Code Description Schema
0 SSL exists ApiError
default unexpected error ApiError

/apisix/admin/consumers

GET

简介

根据指定的页码和页面大小返回消费者列表,可以通过用户名搜索消费者。

参数
Name Located in Description Required Schema
page query page number No integer
page_size query page size No integer
username query username of consumer No string
返回
Code Description Schema
0 list response [ consumer ]
default unexpected error ApiError

/apisix/admin/notexist/routes

GET

简介

路由的返回结果通过名称和排除ID检查是否存在

参数
Name Located in Description Required Schema
name query name of route No string
exclude query id of route that exclude checking No string
返回
Code Description Schema
0 route not exists ApiError
default unexpected error ApiError

/apisix/admin/routes

GET

简介

根据指定的页码和页面大小返回路由列表,可以按名称和uri搜索路由

参数
Name Located in Description Required Schema
page query page number No integer
page_size query page size No integer
name query name of route No string
uri query uri of route No string
label query label of route No string
返回
Code Description Schema
0 list response [ route ]
default unexpected error ApiError

/apisix/admin/services

GET

简介

根据指定的页码和页面大小返回服务列表,并可按名称搜索服务

参数
Name Located in Description Required Schema
page query page number No integer
page_size query page size No integer
name query name of service No string
返回
Code Description Schema
0 list response [ service ]
default unexpected error ApiError

/apisix/admin/ssl

GET

简介

根据指定的页码和页面大小返回 SSL 列表,可以通过 sni 进行 SSL 搜索。

参数
Name Located in Description Required Schema
page query page number No integer
page_size query page size No integer
sni query sni of SSL No string
返回
Code Description Schema
0 list response [ ssl ]
default unexpected error ApiError

/apisix/admin/upstreams

GET

简介

根据指定的页码和页面大小返回上游列表,可以按名称搜索上游

参数
Name Located in Description Required Schema
page query page number No integer
page_size query page size No integer
name query name of upstream No string
返回
Code Description Schema
0 list response [ upstream ]
default unexpected error ApiError

/apisix/admin/user/login

POST

简介

用户登录.

参数
Name Located in Description Required Schema
username body user name Yes string
password body password Yes string
返回
Code Description Schema
0 login success ApiError
default unexpected error ApiError

Models

ApiError

Name Type Description Required
code long response code No
message string response message No

BaseInfo

Name Type Description Required
create_time long No
id object No
update_time long No

Consumer

Name Type Description Required
create_time long No
desc string No
id object No
labels object No
plugins object No
update_time long No
username string No

LoginInput

Name Type Description Required
password string password No
username string user name No

Route

Name Type Description Required
create_time long No
desc string No
enable_websocket boolean No
filter_func string No
host string No
hosts [ string ] No
id object No
labels object No
methods [ string ] No
name string No
plugins object No
priority long No
remote_addr string No
remote_addrs [ string ] No
script object No
service_id object No
service_protocol string No
update_time long No
upstream UpstreamDef No
upstream_id object No
uri string No
uris [ string ] No
vars object No

SSL

Name Type Description Required
cert string No
certs [ string ] No
create_time long No
exptime long No
id object No
key string No
keys [ string ] No
labels object No
sni string No
snis [ string ] No
status long No
update_time long No
validity_end long No
validity_start long No

Service

Name Type Description Required
create_time long No
desc string No
enable_websocket boolean No
id object No
labels object No
name string No
plugins object No
script string No
update_time long No
upstream UpstreamDef No
upstream_id object No

Upstream

Name Type Description Required
checks object No
create_time long No
desc string No
hash_on string No
id object No
k8s_deployment_info object No
key string No
labels object No
name string No
nodes object No
pass_host string No
retries long No
service_name string No
timeout object No
type string No
update_time long No
upstream_host string No

UpstreamDef

Name Type Description Required
checks object No
desc string No
hash_on string No
k8s_deployment_info object No
key string No
labels object No
name string No
nodes object No
pass_host string No
retries long No
service_name string No
timeout object No
type string No
upstream_host string No

标签:APISIX,string,No,name,文档,Dashboard,Description,apisix,description
来源: https://www.cnblogs.com/zx-admin/p/16450447.html