github.com/circl-dev/go-swagger@v0.31.0/examples/external-types/example-external-types.yaml

---
swagger: "2.0"
info:
  version: "1.0"
  title: "external types imports: external anonymous types"
  description: |
    This sample specification exercises external types, with both x-go-type in definitions and inlined.

    It demonstrates how to use the x-go-type extension to plug external type definitions in the generated code,
    for models (e.g. for properties, arrays or maps) or operations.

    Notice that x-go-type works for schemas and is not supported for simple swagger types,
    used for response headers and query & path parameters.

paths:
  /test:

    get:
      responses:
        default:
          description: |
            A reference to a type already defined in the models package
            (defaults to <<target>/models, defined by CLI flag --model-package).
            The response payload is defined as: *models.Zzz

          schema:
            $ref: "#/definitions/Zzz"

    put:
      parameters:
        - in: body
          name: myAlternate
          required: true
          description: |
            A reference to a type defined in the "fred" package, aliased
            as "alternate".

            MyAlternate alternate.MyAlternateType

          schema:
            $ref: '#/definitions/MyCustom'

      responses:
        default:
          description: |
            A map of an aliased external package. Now the alias is "custom".
            This response is defined as: map[string]custom.MyAlternateString

          schema:
            type: object
            additionalProperties:
              type: object
              description: |
                This uses the external type from an inline definition, without $ref

              x-go-type:
                type: MyAlternateString
                import:
                  package: "github.com/circl-dev/go-swagger/examples/external-types/fred"
                  alias: custom

    post:

      parameters:
        - in: body
          name: customizedStrings
          description: |
            Defines a parameter as an array of external types.
            The body parameter is defined as []custom.MyAlternateString

            No definition is generated in models.
          schema:
            type: array
            items:
              type: string
              x-go-type:
                type: MyAlternateString
                import:
                  package: "github.com/circl-dev/go-swagger/examples/external-types/fred"
                  alias: custom

      responses:
        default:
          description: |
            An inlined reference to an aliased external package.
            The response is defined as map[string][]map[string]custom.MyAlternateString

            No definition is generated in models.
          schema:
            type: object
            additionalProperties:
              type: array
              items:
                type: object
                additionalProperties:
                  x-go-type:
                    type: MyAlternateString
                    import:
                      package: "github.com/circl-dev/go-swagger/examples/external-types/fred"
                      alias: custom

  /stream:
    get:
      responses:
        default:
          description: |
            Uses an external definition for an interface (e.g. io.Reader)

            No validation is expected on binary format.

          schema:
            $ref: "#/definitions/MyReader"

definitions:
  Zzz:
    description: |
      This demonstrates variations in generated code, depending on how properties are declared.

      Some properties are directly based on some external type and some other define collections (slices, maps)
      of these external types.

      Notice the use of pointers for required properties, but not for slices or maps.

      In addition, it demonstrates how pointer generation may be controlled with the nullable hint or the x-nullable extension.

      type Zzz struct {
      	Beta []MyOtherType `json:"beta"`
      	Delta MyInteger `json:"delta,omitempty"`
      	Epsilon []custom.MyAlternateType `json:"epsilon"`
      	Gamma fred.MyAlternateInteger `json:"gamma,omitempty"`
      	Meta MyType `json:"meta,omitempty"`

      	NullableBeta []*MyOtherType `json:"nullableBeta"`
      	NullableDelta *MyInteger `json:"nullableDelta,omitempty"`
      	NullableEpsilon []*custom.MyAlternateType `json:"nullableEpsilon"`
      	NullableGamma *fred.MyAlternateInteger `json:"nullableGamma,omitempty"`
      	NullableMeta MyType `json:"nullableMeta,omitempty"`

      	ReqBeta []MyOtherType `json:"reqBeta"`
      	ReqDelta *MyInteger `json:"reqDelta"`
      	ReqEpsilon []custom.MyAlternateType `json:"reqEpsilon"`
      	ReqGamma *fred.MyAlternateInteger `json:"reqGamma"`
      	ReqMeta *MyType `json:"reqMeta"`
      }

    type: object
    required: [ reqBeta, reqDelta, reqGamma, reqEpsilon, reqMeta ]
    properties:
      meta:
        $ref: '#/definitions/MyType' # <- a property based on an external type definition (see below)

      beta:
        description: |
          This property defines an array of external types (in the same package).

          []MyOtherType

          The maxItems validation is generated and the external validation is called for every item.

        type: array
        maxItems: 15
        items:
          type: object
          x-go-type:
            type: MyOtherType

      delta:
        description: |
          A type is provided (integer), and the implementation is an external type in the same package.

          The maximum validation remains documentary and is ignored by the generated code.

        type: integer
        maximum: 15
        x-go-type:
          type: MyInteger

      gamma:
        description: |
          Property defined as an external type from package "fred"

        x-go-type:
          type: MyAlternateInteger
          import:
            package: "github.com/circl-dev/go-swagger/examples/external-types/fred"

      epsilon:
        type: array
        items:
          type: object
          x-go-type:
            type: MyAlternateType
            import:
              package: "github.com/circl-dev/go-swagger/examples/external-types/fred"
              alias: custom

      reqMeta:
        $ref: '#/definitions/MyType'

      reqBeta:
        type: array
        items:
          type: object
          x-go-type:
            type: MyOtherType

      reqDelta:
        type: integer
        x-go-type:
          type: MyInteger

      reqGamma:
        x-go-type:
          type: MyAlternateInteger
          import:
            package: "github.com/circl-dev/go-swagger/examples/external-types/fred"

      reqEpsilon:
        type: array
        items:
          type: object
          x-go-type:
            type: MyAlternateType
            import:
              package: "github.com/circl-dev/go-swagger/examples/external-types/fred"
              alias: custom

      nullableMeta:
        $ref: '#/definitions/MyType' # <- a property based on an external type definition (see below)
        x-nullable: true             # <- this is ignored because it is next to a $ref

      nullableBeta:
        description: |
          This property defines an array of external types (in the same package).

          []MyOtherType

          The maxItems validation is generated and the external validation is called for every item.

        type: array
        maxItems: 15
        items:
          type: object
          x-go-type:
            type: MyOtherType
            hints:
              nullable: true

      nullableDelta:
        description: |
          A type is provided (integer), and the implementation is an external type in the same package.

          The maximum validation remains documentary and is ignored by the generated code.

          NullableDelta *MyInteger

        type: integer
        maximum: 15
        x-go-type:
          type: MyInteger
        x-nullable: true

      nullableGamma:
        description: |
          Property defined as an external type from package "fred", with a nullable hint for the
          external type.

          NullableGamma *fred.MyAlternateInteger `json:"nullableGamma,omitempty"`

        x-go-type:
          type: MyAlternateInteger
          import:
            package: "github.com/circl-dev/go-swagger/examples/external-types/fred"
          hints:
            nullable: true

      nullableEpsilon:
        description: |
          In this example, items are made nullable.

          NullableEpsilon []*custom.MyAlternateType `json:"nullableEpsilon"`

        type: array
        items:
          type: object
          x-go-type:
            type: MyAlternateType
            import:
              package: "github.com/circl-dev/go-swagger/examples/external-types/fred"
              alias: custom
          x-nullable: true


  MyType:
    description: |
      The generated code expects this type to be already defined in the models package
      (default location when no package is specified).

    type: object
    x-go-type:
      type: MyType

  MyCustom:
    description: |
      The generated code expects this type to be already defined in the "fred" package.
      An alias is used by the generated code. Aliases are convenient to avoid
      conflicts with other imports or variables in the generated code.

    type: object
    x-go-type:
      type: MyAlternateType
      import:
        package: "github.com/circl-dev/go-swagger/examples/external-types/fred"
        alias: alternate

  MyCustomArray:
    description: |
      This generate an array type in models, based on the external type.

      []alternate.MyAlternateType

      The validation method of the external type is called by the generated array.

    type: array
    items:
      type: object
      x-go-type:
        type: MyAlternateType
        import:
          package: "github.com/circl-dev/go-swagger/examples/external-types/fred"
          alias: alternate

  MyCustomArrayNullable:
    description: |
      This generate an array type in models, based on the external type.
      Notice the impact of the nullable hint (equivalent to x-nullable at the type level), to produce a slice of pointers.

      []*alternate.MyAlternateType

    type: array
    items:
      type: object
      x-go-type:
        type: MyAlternateType
        import:
          package: "github.com/circl-dev/go-swagger/examples/external-types/fred"
          alias: alternate
        hints:
          nullable: true

  MyCustomMap:
    description: |
      This generate a map type in models, based on the external type.

      MyCustomMap map[string]map[string]alternate.MyAlternateType

      The validation method of the external type is called by the generated map.

    type: object
    additionalProperties:
      type: object
      additionalProperties:
        type: object
        x-go-type:
          type: MyAlternateType
          import:
            package: "github.com/circl-dev/go-swagger/examples/external-types/fred"
            alias: alternate

  MyCustomMapNullable:
    description: |
      This generate a map type in models, based on the external type.
      Notice the impact of the x-nullable directive, to produce a map of pointers.

      MapNullable map[string]map[string]*alternate.MyAlternateType

    type: object
    additionalProperties:
      type: object
      additionalProperties:
        type: object
        x-go-type:
          type: MyAlternateType
          import:
            package: "github.com/circl-dev/go-swagger/examples/external-types/fred"
            alias: alternate
        x-nullable: true

  MyReader:
    description: |
      This is an external type replacing the io.Reader type normally generated.

      No validation is called on such a type.

    type: string
    format: binary
    x-go-type:
      type: MyStreamer

  MyInterface:
    description: |
      This is an external type replacing the interface{} type normally generated.

      No validation is called on such a type.

      This demonstrates how to use hints in x-go-type: by default, the generator
      assumes a struct with some Validate method.

      By providing the "interface" hint, validation is disabled. Notice that we don't
      generate pointers on interfaces.

      If no hint is provided, the generate code won't compile is the MyAlternateInterface
      does not provide a Validate method.

    x-go-type:
      type: MyAlternateInterface
      import:
        package: "github.com/circl-dev/go-swagger/examples/external-types/fred"
      hints:
        kind: interface

  MyExtStruct:
    description: |
      This type is located in a package which requires name mangling.

    x-go-type:
      type: MyExtType
      import:
        package: "github.com/circl-dev/go-swagger/examples/external-types/go-ext"

  MyExtCollection:
    description: |
      This type demonstrates the import generation with name mangling

    type: array
    items:
      $ref: '#/definitions/MyExtStruct'

  MyReaderObject:
    description:
      This object demonstrates several ways to refer to an external interface (here assumed akin to io.Reader).

      MarshalBinary() methods are generated. No validation is expected on binary format.

    type: object
    properties:
      reader1:
        $ref: '#/definitions/MyReader'  # <- reuse external definition from spec
      reader2:
        description: |
          In line definition of the external type.

          Notice that we have provided some information in the spec, so the generator
          can infer we want it to be understood as an io.Reader, with no validation.

        type: string
        format: binary
        x-go-type:
          type: MyAlternateStreamer
          import:
            package: "github.com/circl-dev/go-swagger/examples/external-types/fred"
            alias: alternate
      reader3:
        description: |
          In line definition of the external type.

          Notice that we have provided some information in the spec, as a hint in the extension
          rather than in the type definition.

          So this will be documented as an object, but the generated code knows this is a stream.

        x-go-type:
          type: MyAlternateStreamer
          import:
            package: "github.com/circl-dev/go-swagger/examples/external-types/fred"
          hints:
            kind: stream

  MyInterfaceObject:
    description: |
      This object demonstrates several ways to refer to an external interface.

      The generated code behaves as it is an interface{}: no pointers are generated, and no valication
      is required.

    type: object
    required: [ iface2, iface3 ]
    properties:
      iface1:
        $ref: '#/definitions/MyInterface'
      iface2:
        description: |
          Demonstrates the impact of the "interface" hint: no validation is called on iface2,
          and no pointer is generated in spite of the "required" directive.

          The generated object validation checks for the "required" directive.

          Without the hint, the generator assumes a Validatable object, with pointer, which may
          not build, depending on how the external type is defined.

        x-go-type:
          type: MyAlternateInterface
          import:
            package: "github.com/circl-dev/go-swagger/examples/external-types/fred"
          hints:
            kind: interface

      iface3:
        description: |
          Demonstrates the impact of the "noValidation" hint.

          Notice how we avoid the generation of a pointer on the required json.RawMessage (which is a []byte)
          with the "nullable" hint.

          Notice that the "json" package is automatically deconflicted from other standard imports with a distinct alias.

        x-go-type:
          type: RawMessage
          import:
            package: "encoding/json"
          hints:
            nullable: false
            noValidation: true

  MyTuple:
    description: |
      Demonstrates references to some external type in the context of a tuple.

      Notice that "additionalItems" is not a construct that pass swagger validation,
      but is supported by go-swagger.

    type: array
    items:
    - $ref: '#/definitions/MyType'
    - type: object
      description: |
        Second element of the tuple, defined as follows.

        P1 *fred.MyAlternateType `json:"-"` // custom serializer

      x-go-type:
        type: MyAlternateType
        import:
          package: "github.com/circl-dev/go-swagger/examples/external-types/fred"
    additionalItems:
      description: |
        Additional items to a tuple, from an external type.
        This defines the following field in the tuple

        MyTupleItems []map[string]fred.MyAlternateType

      type: object
      additionalProperties:
        x-go-type:
          type: MyAlternateType
          import:
            package: "github.com/circl-dev/go-swagger/examples/external-types/fred"

  EmbeddedTime:
    description: |

      This type demonstrates how we can embed an external type and wraps the validation.

      This is especially useful if you want to reuse some types from the standard library,
      such as `time.Time` or `json.RawMessage`.

    x-go-type:
      type: Time
      import:
        package: time
      embedded: true

  NoValidateExternal:
    description: |

      This type demonstrates how we can disable validation for an external type.

      This is useful if you want to reuse some types from the standard library and don't
      want to resort to an embedded type.

    x-go-type:
      type: Request
      import:
        package: net/http
      hints:
        noValidation: true

  ObjectWithNoValidate:
    description: |
      A reference to the NoValidateExternal external type.

      If the "noValidation" hint is omitted in the definition above, this code won't build because `http.Request` has no `Validate` method.

    type: object
    properties:
      request:
        $ref: '#/definitions/NoValidateExternal'

  NoValidateExternal:
    description: |

      This type demonstrates how we can disable validation for an external type.

      This is useful if you want to reuse some types from the standard library and don't
      want to resort to an embedded type.

    type: object
    x-go-type:
      type: Request
      import:
        package: net/http
      hints:
        noValidation: true

  ObjectWithNoValidate:
    description: |
      A reference to the NoValidateExternal external type.

      If the "noValidation" hint is omitted in the definition above, this code won't build because `http.Request` has no `Validate` method.

    type: object
    required: [ myMandatoryRequest ]
    properties:
      myRequest:
        $ref: '#/definitions/NoValidateExternal'
      myMandatoryRequest:
        $ref: '#/definitions/NoValidateExternal'

  ArrayWithNoValidate:
    description: |
      A slice of NoValidateExternal external types.

      If the "noValidation" hint is omitted in the definition above, this code won't build because `http.Request` has no `Validate` method.

    type: array
    maxItems: 12
    uniqueItems: true
    items:
      $ref: '#/definitions/NoValidateExternal'

  MapWithNoValidate:
    description: |
      A map of NoValidateExternal external types.

      If the "noValidation" hint is omitted in the definition above, this code won't build because `http.Request` has no `Validate` method.

    type: object
    additionalProperties:
      $ref: '#/definitions/NoValidateExternal'

  TupleWithNoValidate:
    description: |
      A tuple of NoValidateExternal external types.

      If the "noValidation" hint is omitted in the definition above, this code won't build because `http.Request` has no `Validate` method.

      Notice that "additionalItems" is not a construct that pass swagger validation,
      but is supported by go-swagger.

    type: array
    items:
    - $ref: '#/definitions/NoValidateExternal'
    - $ref: '#/definitions/NoValidateExternal'
    additionalItems:
      $ref: '#/definitions/NoValidateExternal'

  NoValidatePrimitive:
    description: |

      This type demonstrates how we can disable validation for an external primitive type.

    type: integer
    x-go-type:
      type: Duration
      import:
        package: time
      hints:
        noValidation: true

  MapOfPrimitives:
    description: |
      A map of NoValidatePrimitive external types.

      If the "noValidation" hint is omitted in the definition above, this code won't build because `time.Duration` has no `Validate` method.

    type: object
    additionalProperties:
      $ref: '#/definitions/NoValidatePrimitive'

  #
  # Currently unsupported constructs: inline definitions of embedded external types
  #
  #
  #  ArrayWithInlinedEmbedded:
  #    type: array
  #    items:
  #      x-go-type:
  #        type: Time
  #        import:
  #          package: time
  #        embedded: true
  #
  #  MapWithInlinedEmbedded:
  #    type: object
  #    additionalProperties:
  #      x-go-type:
  #        type: Time
  #        import:
  #          package: time
  #        embedded: true
  #
  #  ObjectWithInlinedEmbedded:
  #    type: object
  #    properties:
  #      p1:
  #        x-go-type:
  #          type: Time
  #          import:
  #            package: time
  #          embedded: true
  #