Ссылка на удаленные параметры 'response's' и 'на $ ref open api 3.0 - PullRequest
Новая
       28

Ссылка на удаленные параметры 'response's' и 'на $ ref open api 3.0

0 голосов
/ 19 декабря 2018

Я создаю хорошо организованную документацию по swasger для OAS3 на swaggerhub.Для каждой конечной точки я пишу все возможные ответы, такие как 200, 201, 204, 400, 401, 403, 404, 500 и т. Д. Кроме того, все методы имеют параметры по умолчанию, такие как X-Language-Code и т. Д. Я нахожусь в таком месте, чтоответы, модели, параметры, которые я использую сейчас, начинают повторяться в каждом файле.После небольшого исследования я узнал, что я могу создать домен и удаленные ссылки на них.Там нет ошибки, когда я использовал определение 'удаленно, как это: 

/example:
    get:
        #some other informations here
        responses:
            200:
                description: 'example description'
                content:
                    application/json:
                        schema:
                            $ref: 'https://remote.example/url/2.0#/definitions/ExampleResponse'

Но, очевидно, вы не можете использовать ключевое слово $ref прямо под responses или 400 и т. Д. Ключевое слово, как это:

Это не ошибка, но не рендеринг удаленной ссылки 

responses:
    400:
        $ref: 'https://remote.example/url/2.0#/responses/Error400'

или это:

Этот выдает ошибку 

responses:
    $ref: 'https://remote.example/url/2.0#/responses'

Даже, я не могу использовать «параметры», как ожидал: 

/example:
    get:
        parameters:
            - languageCode:
                $ref: 'https://remote.example/url/2.0#/parameters/languageCode'

/example:
    get:
        parameters:
            - $ref: 'https://remote.example/url/2.0#/parameters/'

Я не хочу переписывать всессылки на определения ниже каждой документации.Я запутался в использовании и ссылках на домены.Может кто-нибудь объяснить или ссылаться на документ об этой ситуации, так как я не смог найти никакой документации об этом.

1 Ответ

0 голосов
/ 19 декабря 2018

Обновление: В SwaggerHub теперь поддерживаются домены OpenAPI 3.0.

С декабря 2018 года домены SwaggerHub поддерживают только синтаксис OpenAPI 2.0, но не OpenAPI 3.0.OpenAPI 3.0 и 2.0 используют немного другой синтаксис для параметров, ответов и т. Д., Это означает, что вы не можете ссылаться на домен OAS2 из определения API OAS3.

Временное решение: создать другой API OpenAPI 3.0 в SwaggerHub и использовать егокак «домен».Вам нужно добавить фиктивный заголовок с openapi: 3.0.0, разделом info и пустым paths: {}, чтобы сделать валидатор счастливым. 

openapi: 3.0.0
info:
  title: Common components
  version: 1.0.0
paths: {}

# Put your common components here:
components:
  schemas:
    ...
  parameters:
    ...
  responses:
    ...

Затем вы можете ссылаться на компоненты из этого "домена", используяобычный синтаксис $ref: 

$ref: 'https://api.swaggerhub.com/apis/USERNAME/API-NAME/VERSION#/components/responses/Error400'

Убедитесь, что имя хоста в $ refs равно API.swaggerhub.com (не APP.swaggerhub.com), а ссылка содержит /apis/ (не /domains/).

...