How are we supposed to generate maintainable openapi files?

[fr-rose-steven]

Imagine you had an api with 10 paths with each 8 operations. That would mean 80 operation objects wrapped in 10 path objects.
This alone creates a file that is not really maintainable anymore.
Problem is you can not reference paths externally, amongst many other things.

I wonder how we are supposed to make clean code here that is maintainable?

With swagger-cli I could create imports or however you call it.
Following this: https://dev.to/mikeralphson/defining-reusable-components-with-the-openapi-specification-4077
I can make them self-contained but I'm currently stuck at paths and how to do it there.

[vvanpo]

Each path item can be a JSON reference object. And JSON references can point to external documents. This means you can split up each path into a separate file, if you really needed to.

[vvanpo]

Problem is you can not reference paths externally

I'm not entirely sure what you mean by this.

JSON references can reference structures within an external document. So let's say you had the 2 files:

/my-api/openapi.yaml:

openapi: 3.0.2
info:
  title: My API
  version: 1.0.0
paths:
  /foo:
    $ref: 'path-items.yaml#/foo'
  /bar:
    $ref: 'path-items.yaml#/bar'
components:
  responses:
    Bar:
      description: A bar
      content:
        application/json:
          schema: { type: object }

/my-api/path-items.yaml:

foo: # this path item is empty
bar:
  get:
    operationId: getBar
    responses:
      '200':
        $ref: 'openapi.yaml#/components/responses/Bar'

Does this example help at all?

[fr-rose-steven]

Yes that's what I meant with imports but you can't validate them.

openapi: 3.0.2
info:
  title: My API
  version: 1.0.0
foo: # this path item is empty
bar:
  get:
    operationId: getBar
    responses:
      '200':
        $ref: 'openapi.yaml#/components/responses/Bar'

Structural error at
should NOT have additional properties
additionalProperty: foo, bar
Jump to line 0

[fr-rose-steven]

For info and servers you could do (not nice but at least):

openapi: 3.0.2
info:
  $ref: 'schema/info/general_info_object.json#/components/schemas/GeneralInfoObject'
servers:
  - $ref: 'server/staging/staging_server_object.json#/servers/0'
  - $ref: 'server/production/production_server_object.json#/servers/0'
paths: ...

info:

openapi: 3.0.2
info:
  title: providing a proper description for this api
  version: 1.0.0
paths: {}
components:
  schemas:
    GeneralInfoObject:
      title: My API
      description: some description

server:

openapi: 3.0.2
info:
  title: description of staging server
  version: 1.0.0
paths: {}
servers:
  - url: 'https://stage-api.domain.com/{v1}/{v2}'
    description: Staging API server for QA
    variables:
      v1:
        $ref: '../server_variables/v1_server_variable_object.json#/components/schemas/V1ServerVariableObject'
      v2:
        $ref: '../server_variables/v2_server_variable_object.json#/components/schemas/V2ServerVariableObject'

ServerVariableObjects are not valid by specification in schemas as well if you'd be hypocritical.

[MikeRalphson]

Closing as answered.