multiple openapi.yaml files show errors

[jahluwalia]

Hi,

I have my spec spread out across multiple *.oas3.yaml files. (e.g. root.oas3.yaml and definitions.oas3.yaml) that use the $ref.

If i "resolve and validate" the root file, I receive a notification that the file is valid.

However, if i go into definitions.oas3.yaml, I see red underlines all over the place. For example "Unexpected property ErrorResponse" among others.

How can we let the extension know that this is part of a larger file structure and not show errors when they aren't really errors.

thanks,
jas

[MikeRalphson]

Is your definitions.oas3.yaml file a fully valid OpenAPI document, i.e. does it include properties openapi, info, paths?

[MikeRalphson]

https://dev.to/mikeralphson/defining-reusable-components-with-the-openapi-specification-4077

[jahluwalia]

Hi @MikeRalphson ,

No it does not. But I don't think a reference file is required to have all that? Two validators (openapi-lint and swagger-cli validate) have verified that the specs are correct (reference files and all).

Another example from my root.oas3.yaml is $ref for each path.

paths:
  /healthcheck:
    $ref: ./healthcheck.oas3.yaml

I don't think it would make sense for healthcheck.oas3.yaml to have paths as well, it wouldn't be valid. The healthcheck.oas3.yaml also refers to objects in definitions.oas3.yaml which is yet another example where it wouldn't make sense to have paths.

I'm wondering if there needs to be a distinction made between to openapi-lint on whether the spec files are to be treated individually or if there is some root file we can specify and it resolves all the references (much like Resolve and Validate does).

I could be wrong in all of this though. Still new to all of this.

Thanks,
Jas

[jahluwalia]

@MikeRalphson just saw your link now. Let me take a look, it may make my post moot.

[jahluwalia]

Hi @MikeRalphson

The article was great and highlighted something for me which was there is no right way of doing things in the spec (so my comment of valid vs invalid probably isn't right).

I wasn't sure how i could maintain my file structure. So an example is as follows:

root.oas3.yaml:

openapi: 3.0.0
info:
  version: 0.0.1
  title: myService
paths:
  /healthcheck:
    $ref: ./healthcheck.oas3.yaml
servers:
  - url: /

healthcheck.oas3.yaml:

get:
    description: Health check 
    operationId: healthcheck
    x-swagger-router-controller: healthcheck
    responses:
        "200":
            description: Service is healthy and all dependencies are up
            content:
                application/json:
                    schema:
                        type: array
                        items:
                            type: string
        default:
            description: Error
            content:
                application/json:
                    schema:
                        $ref: "./definitions.oas3.yaml#/ErrorResponse"

definitions.oas3.yaml:

ErrorResponse:
    required:
        - message
    properties:
        message:
            type: "string"
            description: "The description of the error"
        code:
            type: "string"
            description: "Identifies the kind of error"

[MikeRalphson]

I would personally structure your files as follows:

openapi: 3.0.0
info:
  version: 0.0.1
  title: myService
paths:
  /healthcheck:
    $ref: "./healthcheck.oas3.yaml#/paths/~1healthcheck"
servers:
  - url: /

openapi: 3.0.0
info:
  title: Healthcheck fragment
  version: 0.0.1
paths:
  /healthcheck:
    get:
        description: Health check 
        operationId: healthcheck
        x-swagger-router-controller: healthcheck
        responses:
            "200":
                description: Service is healthy and all dependencies are up
                content:
                    application/json:
                        schema:
                            type: array
                            items:
                                type: string
            default:
                description: Error
                content:
                    application/json:
                        schema:
                            $ref: "./definitions.oas3.yaml#/components/schemas/ErrorResponse"

openapi: 3.0.0
info:
  title: Definitions fragment
  version: 0.0.1
paths: {}
components:
  schemas:
    ErrorResponse:
        required:
            - message
        properties:
            message:
                type: "string"
                description: "The description of the error"
            code:
                type: "string"
                description: "Identifies the kind of error"

The path in healthcheck.oas3.yaml could in fact be anything (including just /) but having it be different from the referring path key might be confusing.

There is a tracking issue on the OAS spec. repository for making the paths object optional in OAS v3.1.0.

[MikeRalphson]

Your examples highlighted a missing option being passed to the resolver, so that's now fixed in v1.0.1. Thanks!

[jahluwalia]

Glad I was able to help, but not sure how :)

I'm going to try to use your model going forward. Thanks for the advice.

[MikeRalphson]

No worries - please feel free to chase up this issue with any further comments. Hopefully it will be helpful to other people too.