Настройка сгенерированной Oracle ORDS документации Swagger - PullRequest
Новая
       39

Настройка сгенерированной Oracle ORDS документации Swagger

0 голосов
/ 11 февраля 2020

Я пишу REST-API, используя Oracle ORDS. ORDS генерирует документацию по API Swagger 2.0 по предопределенному URL.

Я не могу найти, как добавить пользовательскую информацию, такую ​​как текст для описания конечной точки или имя и схема для «объекта», возвращаемого из конечной точки.

Кто-нибудь здесь знает, как настроить документацию Swagger, сгенерированную ORDS?

1 Ответ

1 голос
/ 11 февраля 2020

Недавно мы усовершенствовали ORDS, чтобы вы могли вставлять пользовательские комментарии в документы OpenAPI в стиле Swagger.

Новые функции в 18.4.0

ENH: 28028432 - значение Echo p_comments в сгенерированную документацию Swagger Более ранние версии

Вот пример -

Определение моего 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;
/

Теперь, если я go к конечной точке OpenAPI для моего модуля Вы можете видеть, что текст описания для обработчика был «внедрен» в документацию по сервису.

«Это плохой пример, не имеет обработки ошибок» - это свободное текстовое поле, поэтому вы можете в основном положите туда все, что вы хотите.

enter image description here

{
"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"
}
}
}
}
}
...