自定义 Oracle ORDS 生成的 Swagger 文档
Customizing the Oracle ORDS generated Swagger documentation
我正在使用 Oracle ORDS 编写 REST-API。
ORDS 在预定义的 URL.
上生成 Swagger 2.0 API 文档
我找不到如何添加自定义信息,例如端点描述的文本或从端点返回的 "object" 的名称和架构。
这里有人知道如何调整 ORDS 生成的 Swagger 文档吗?
我们最近增强了 ORDS,这样您就可以将自定义注释插入 Swagger 风格的 OpenAPI 文档中。
New Features in 18.4.0
ENH:28028432 - Echo p_comments value into generated Swagger
documentation Earlier versions
举个例子 -
定义我的 POST
BEGIN
ORDS.DEFINE_HANDLER(
p_module_name => 'EXAMPLES',
p_pattern => 'id/',
p_method => 'POST',
p_source_type => 'plsql/block',
p_items_per_page => 0,
p_mimes_allowed => 'application/json',
p_comments => 'This is a bad example, has no error handling',
p_source =>
'begin
insert into identity_table (words) values (:words);
commit;
end;'
);
COMMIT;
END;
/
现在,如果我转到模块的 OpenAPI 端点,您可以看到处理程序的描述文本已 'injected' 到服务文档中。
"This is a bad example, has no error handling" -- 这是一个自由文本字段,因此您基本上可以在其中放置任何内容。
{
"swagger": "2.0",
"info": {
"title": "ORDS generated API for EXAMPLES",
"version": "1.0.0"
},
"host": "localhost:8080",
"basePath": "/ords/pdb2/jeff/examples",
"schemes": [
"http"
],
"produces": [
"application/json"
],
"paths": {
"/id/": {
"get": {
"description": "Retrieve records from EXAMPLES",
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "The queried record.",
"schema": {
"type": "object",
"properties": {
"ID": {
"$ref": "#/definitions/NUMBER"
},
"WORDS": {
"$ref": "#/definitions/VARCHAR2"
}
}
}
}
},
"parameters": []
},
"post": {
"description": "This is a bad example, has no error handling",
"responses": {
"201": {
"description": "The successfully created record.",
"schema": {
"type": "object",
"properties": {}
}
}
},
"consumes": [
"application/json"
],
"parameters": [
{
"name": "payload",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/EXAMPLES_ITEM"
}
}
]
}
},
"/id/{pk}": {
"get": {
"description": "Retrieve records from EXAMPLES",
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "The queried record.",
"schema": {
"type": "object",
"properties": {
"ID": {
"$ref": "#/definitions/NUMBER"
},
"WORDS": {
"$ref": "#/definitions/VARCHAR2"
}
}
}
}
},
"parameters": [
{
"name": "pk",
"in": "path",
"required": true,
"type": "string",
"description": "implicit",
"pattern": "^[^/]+$"
}
]
}
}
},
"definitions": {
"NUMBER": {
"type": "number"
},
"VARCHAR2": {
"type": "string"
},
"EXAMPLES_ITEM": {
"properties": {
"words": {
"type": "string"
}
}
}
}
}
我正在使用 Oracle ORDS 编写 REST-API。 ORDS 在预定义的 URL.
上生成 Swagger 2.0 API 文档我找不到如何添加自定义信息,例如端点描述的文本或从端点返回的 "object" 的名称和架构。
这里有人知道如何调整 ORDS 生成的 Swagger 文档吗?
我们最近增强了 ORDS,这样您就可以将自定义注释插入 Swagger 风格的 OpenAPI 文档中。
New Features in 18.4.0
ENH:28028432 - Echo p_comments value into generated Swagger documentation Earlier versions
举个例子 -
定义我的 POST
BEGIN
ORDS.DEFINE_HANDLER(
p_module_name => 'EXAMPLES',
p_pattern => 'id/',
p_method => 'POST',
p_source_type => 'plsql/block',
p_items_per_page => 0,
p_mimes_allowed => 'application/json',
p_comments => 'This is a bad example, has no error handling',
p_source =>
'begin
insert into identity_table (words) values (:words);
commit;
end;'
);
COMMIT;
END;
/
现在,如果我转到模块的 OpenAPI 端点,您可以看到处理程序的描述文本已 'injected' 到服务文档中。
"This is a bad example, has no error handling" -- 这是一个自由文本字段,因此您基本上可以在其中放置任何内容。
{
"swagger": "2.0",
"info": {
"title": "ORDS generated API for EXAMPLES",
"version": "1.0.0"
},
"host": "localhost:8080",
"basePath": "/ords/pdb2/jeff/examples",
"schemes": [
"http"
],
"produces": [
"application/json"
],
"paths": {
"/id/": {
"get": {
"description": "Retrieve records from EXAMPLES",
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "The queried record.",
"schema": {
"type": "object",
"properties": {
"ID": {
"$ref": "#/definitions/NUMBER"
},
"WORDS": {
"$ref": "#/definitions/VARCHAR2"
}
}
}
}
},
"parameters": []
},
"post": {
"description": "This is a bad example, has no error handling",
"responses": {
"201": {
"description": "The successfully created record.",
"schema": {
"type": "object",
"properties": {}
}
}
},
"consumes": [
"application/json"
],
"parameters": [
{
"name": "payload",
"in": "body",
"required": true,
"schema": {
"$ref": "#/definitions/EXAMPLES_ITEM"
}
}
]
}
},
"/id/{pk}": {
"get": {
"description": "Retrieve records from EXAMPLES",
"produces": [
"application/json"
],
"responses": {
"200": {
"description": "The queried record.",
"schema": {
"type": "object",
"properties": {
"ID": {
"$ref": "#/definitions/NUMBER"
},
"WORDS": {
"$ref": "#/definitions/VARCHAR2"
}
}
}
}
},
"parameters": [
{
"name": "pk",
"in": "path",
"required": true,
"type": "string",
"description": "implicit",
"pattern": "^[^/]+$"
}
]
}
}
},
"definitions": {
"NUMBER": {
"type": "number"
},
"VARCHAR2": {
"type": "string"
},
"EXAMPLES_ITEM": {
"properties": {
"words": {
"type": "string"
}
}
}
}
}