How to split requests, responses, schemas into separate files

[mrmeyers99]

I've been able to merge paths in from multiple files, but we haven't been able to figure out how to split the requests, responses, and schemas into separate schemas. I've created a sample repo that shows what I'm trying to do, and as you can see from the github actions worfklow I get the following error:

/components/requests/helloWorldPayload/content/application~1json/schema: content replaced from /github/workspace/schemas.yaml

Here are the files that I have, but see my github link to download the code if you need it.

spec.yaml (root file)

openapi: 3.0.3
info:
  title: Test spec
  description: |-
    Test spec
  version: 1.0.0

paths:
  $inline: paths.yaml#/paths

paths.yaml

openapi: 3.0.3
info:
  title: Paths
  description: Paths
  version: 1.0.0

paths:
  /helloWorld:
    post:
      description: Say hello
      requestBody:
        $ref: "requests.yaml#/components/requests/helloWorldPayload"
      responses:
        "200":
          $ref: "responses.yaml#/components/responses/helloWorldResponse"

requests.yaml

openapi: 3.0.3
components:
  requests:
    helloWorldPayload:
      content:
        application/json:
          schema:
            $ref: "schemas.yaml#/components/schemas/helloWorldRequestSchema"

responses.yaml

openapi: 3.0.3
components:
  responses:
    helloWorldResponse:
      description: OK
      content:
        application/json:
          schema:
            $ref: 'schemas.yaml#/components/schemas/hellowWorldResponseSchema'

schemas.yaml

openapi: 3.0.1
components:
  schemas:
    helloWorldRequestSchema:
      type: object
      properties:
        name:
          type: string
          description: name

    hellowWorldResponseSchema:
      type: object
      properties:
        message:
          type: string
          description: name

Is what I'm trying to do possible?

[dolmen]

On a first look, everything looks good in your input so the reported $ref resolution error looks like a bug.

[mrmeyers99]

It would be great if this could get fixed, we have a really big spec I'd like to break up. Thanks for taking a look.

[dolmen]

There are currently some limitation in the implementation. Deciding between importing (rewriting the document) early or late is tough.

The workaround is to use the -debug=trace flag on the command line to see where resolution goes wrong, and then to workaround $ref issues by including redundant references that will help the resolver to process references and $inline in a different order.

For example (not tested), you could modify requests.yaml like this:

openapi: 3.0.3
components:
  requests:
    helloWorldPayload:
      content:
        application/json:
          schema:
            $ref: "spec.yaml#/components/schemas/helloWorldRequestSchema"

and spec.yaml:

openapi: 3.0.3
info:
  title: Test spec
  description: |-
    Test spec
  version: 1.0.0

paths:
  $inline: paths.yaml#/paths
components:
  schemas:
    $inline: "schemas.yaml#/components/schemas"

I'm not guaranteeing that this exact suggestion will work, however by playing such tricks you should be able to get to a working state. The key is to help openapi-preprocessor to not get into a deep recursion of includes.

Another trick is to create placeholders in the main document where parts of other documents will be injected: create empty /components/schemas, /components/responses, /components/requests in spec.yaml.