Define OpenAPI domains locally and avoid publishing on SwaggerHub

Question

I'm tinkering with OpenAPI and I would like to make my components definition available in a separate file. I understand that this is achieved through domains created on SwaggerHub. My problem is that I am at the stage when I am still playing around and would love to avoid publishing stuff on a third-party site.

Is there a way to reference a domain with $ref a local file (and avoid referencing a file on SwaggerHub.com)?

score 3 · Answer 1 · answered Aug 15 '22 at 07:46

3

If you create the definition manually like (Can be a separate file).

definitions:
  SuccessResponse:
    type: object
    properties:
      message:
        type: string
        description: API response message
      status:
        type: boolean
      code:
        type: number
        description: Api Response Code
      data:
        type: object
        description: data will be available here

Then it can be referenced in your API definition using $ref like:

responses: # server responses
    200:
      description: Response when le0 run successfully
      content:
        application/json:
          schema:
            $ref: "#/definitions/SuccessResponse"

answered Aug 15 '22 at 07:46

Santosh Subedi

71
6

Apologies, but there is something that is still unclear to me (and it might very well be me who's missing something). My understanding is that definition taken from a domain will have the form: $ref: 'https://api.swaggerhub.com/domains/myproj/mydom/1.0.0#/components/schemas/SuccessResponse wouldn't I need to have something like: $ref: "mydefs#/components/schemas/SuccessResponse" where mydef is a mydef.yaml file or something like that? – Luca P. Aug 15 '22 at 19:44
This document seems to indicate that it is in fact possible to reference a different file on the same file system through a "remote reference": https://swagger.io/docs/specification/using-ref/ – Luca P. Aug 15 '22 at 20:54

score 0 · Accepted Answer · answered Aug 16 '22 at 14:10

Just to close the loop, I'll answer my own question here. The person who answered my question above did help put me on the right track, but I can't honestly say that he answered my question.

I guess that what confused me initially was a (all things considered good) Swagger tutorial on Linkedin that explained how to do Local References, and then jumped to explaining SwaggerHub "domains" as (what appeared as the only way to) the path to reusable schema definitions.

It turns out that the answer to my question was as simple as:

$ref: './my-schemas.yaml#/components/schemas/myGoodStuff'

This is referred to as Remote Reference in the https://swagger.io/docs/specification/using-ref/.

Define OpenAPI domains locally and avoid publishing on SwaggerHub

2 Answers2