定制Oracle ORDS生成的Swagger文档

Posted 2023-02-01

我正在使用Oracle ORDS编写REST-API。ORDS在预定义的URL上生成Swagger 2.0 API文档。

我找不到如何添加自定义信息，例如为端点描述添加文本或从端点返回的“对象”的名称和架构。

这里有人知道如何调整ORDS生成的Swagger文档吗？

答案

我们最近增强了ORDS，以便您可以将自定义注释插入到Swagger风格的OpenAPI文档中。

[18.4.0中的新功能

ENH：28028432-将p_comments值回显到生成的Swagger中文档早期版本

这里是一个例子-

定义我的帖子

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端点，则可以看到处理程序的描述文本已“注入”到服务文档中。

“这是一个糟糕的例子，没有错误处理”-这是一个自由文本字段，因此您基本上可以在其中放置任何想要的内容。

"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"