Referencing remote 'response's and 'parameter's on $ref open api 3.0

Question

I am creating a well-organized OAS3 swagger documentation on swaggerhub. For every endpoint i am writing all possible answers like 200, 201, 204, 400, 401, 403, 404, 500 etc. In addition all methods have default parameters like X-Language-Code etc. I am in such a place that the responses, models, parameters I use now begin to repeat themselves in each file. After a little research i learnt that i can create a domain and remote absolute url references to them. There is no error when i used the 'definition's remotely like this:

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

But, apparently you can not use $ref keyword right below responses or 400 etc.. keyword like this:

This one not getting error but not rendering the remote reference

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

or this:

This one gives error

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

Even, i can not use 'parameters' as i expected:

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

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

I dont want to rewrite all reference definitions below every documentation. I am confused about using and referencing 'domain's. Can someone explain or referencing a document about this situations since i couldn't found any documentation about it.

Helen · Accepted Answer · 2019-08-21T11:12:57.470

Update: OpenAPI 3.0 domains are now supported in SwaggerHub.

As of December 2018, SwaggerHub domains only support the OpenAPI 2.0 syntax but not OpenAPI 3.0. OpenAPI 3.0 and 2.0 use slightly different syntax for parameters, responses, etc., this means you cannot reference an OAS2 domain from an OAS3 API definition.

The workaround is to create another OpenAPI 3.0 API in SwaggerHub and use it as a "domain". You'll need to add a dummy header with openapi: 3.0.0, the info section and empty paths: {} to make the validator happy.

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

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

Then you can reference components from this "domain" using the usual $ref syntax:

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

Make sure the hostname in $refs is API.swaggerhub.com (not APP.swaggerhub.com) and the link contains /apis/ (not /domains/).

Referencing remote 'response's and 'parameter's on $ref open api 3.0

1 Answers1