@dasaplan/openapi-bundler

• ✅ Configured wrapper of the standard redocly bundler.
• ✅ Includes opinionated post-processing steps to transform the spec in a OpenApi 3.0.3 standard compliant way (see spec-rules).
• ✅ Is implemented against OpenApi 3.0.3.

Getting started

Prerequisite

• using npm

  # integrate in project
  npm i --save-dev @dasaplan/openapi-bundler

  # global installation
  npm i -g @dasaplan/openapi-bundler

• using pnpm

  # integrate in project
  pnpm i --save-dev @dasaplan/openapi-bundler

  # global installation
  pnpm i -g @dasaplan/openapi-bundler

usage

• Bundle an OpenapiSpec

  # assuming the root spec file is located at "$cwd/specs/generic/api.yml"
  # and assuming we want all generated files to find at "$cwd/out"
  openapi-bundler-cli bundle specs/generic/api.yml -o ./out/bundled-api.yml

• See help for more options

  openapi-bundler-cli bundle --help

Features

• ✅ Configured wrapper of the standard redocly bundler.

note: Example specs are written in a compressed but valid way to reduce whitespace and facilitate an overview over the whole example.

post processing

# schema declares $ref property but also other properties:
# most tools ignore everything besides $ref
# -> 🔥 unspecified behavior across tooling and use cases
RefSchema_with_dangling_properties:
  $ref: '#/A_Schema'
  description: "This is something I like to share!"
  title: RefSchema_with_dangling_properties

# schema declares allOf but declares further properties:
# most tool will merge siblings into array, but some may ignore them 
# -> 🔥 inconsistent behavior across tooling and use cases
AllOfSchema_with_dangling_properties:
  allOf: [ { $ref: '#/A_Schema'} ]
  properties: # sibling to allOf should be part of allOF
    name: { type: string }

# schema declares allOf with multiple elements:
# no problem for validators but code gen mostly try to merge them
# -> 🔥 merge behaviour may yield unexpected results
AllOfSchema_with_multi_elements:
  allOf:
    - $ref: '#/A_Schema',
    - $ref: '#/B_Schema',
    - properties: { foo: { type: string } }

components:
  schemas:
    PetBase: 
      type: object,
      properties: { type: { type: string } }
    
    CatBase:  
      type: object,
      discriminator: { propertyName: catType },
      properties: 
        type: { type: string }, 
        catType: { type: string, enum: [ 'SEAM', 'SHORT_HAIR' ] } 

    SeamCat:
      allOf:
        - $ref: '#/components/PetBase'
        - $ref: '#/components/CatBase'
        - title: SeamCat
    ShortHairCat:
      allOf:
        - $ref: '#/components/PetBase'
        - $ref: '#/components/CatBase'
        - title: ShortHairCat

    Dog: { allOf: [ { $ref: '#/components/PetBase' }, { title: Dog } ] }

components:
  schemas:
    PetBase: { type: object, required: [type] discriminator: {propertyName: type},properties: { type: { type: string } } }

    SeamCat:
      allOf:
        - $ref: '#/components/PetBase'
        - { title: SeamCat, type: object, properties: { type: { catType: string, enum: [ 'SEAM', 'SHORT_HAIR' ] } } }

    ShortHairCat:
      allOf:
        - $ref: '#/components/PetBase'
        - { title: ShortHairCat, type: object, properties: { type: { catType: string, enum: [ 'SEAM', 'SHORT_HAIR' ] } } }

    Dog:
      allOf:
        - $ref: '#/components/PetBase'
        - title: Dog 

• ensures that:
  • discriminator property type is of type string, and not enum.
    • most sophisticated tools can infer the values from the explicit or implicit discriminator mapping
  • polymorphism and inheritance can be explicitly inferred from the spec
    • every polymorph subschema defines the discriminator property and respective value
      • this is only necessary to extend the standard generator with templating
      • discriminator value is declared with x-const to avoid triggering compatibility layers for discriminator
    • any parent schema referenced from an allOf array does not define discriminator mapping
    • discriminator mapping only exists on schemas with a oneOf member

Cat:
  type: object
  properties:
    type: 
      type: string
      x-const: [ 'SEAM', 'SHORT_HAIR' ]
    
MyOneOfSchema:
  oneOf: [{$ref: '#/Dog', {$ref: '#/Cat'}}]
  discriminator:
    propertyName: 'type'
    mapping:
      SEAM: "#/Cat"
      SHORT_HAIR: "#/Cat"
      Dog: "#/Dog"

| examples | src | bundled | post-processed | |----------|-------------------------------------|---------------------------------------------|------------------------------------------------------| | simple | link to src | link to bundled | link to post-processed | | complex | link to src | link to bundled | link to post-processed |