Swagger Definition of primitive types

Question

Is it possible to define a swagger definition/model for a primitive type? For instance, consider the following

definitions:
  program_name:
    type: string
    description: Unique string id

However, the above example comes back with many errors (swagger expects a properties field for example) and no examples employ any definition that is not of type: object.

The intention is to use this as a subcomponent to another model as well as a parameter -- to reuse the already defined component in some way.

Think of this as a swagger typedef

EDIT: According to the spec, a definition object is the same as a schema object http://swagger.io/specification/#schemaObject, which states that it can accept primitive types.

Also, assuming that primitive types can exist in the definitions section, could simple parameter types (query, path etc.) reference primitive definition types?

Helen Helen · Accepted Answer · 2017-04-19T20:55:31

A primitive schema as in your example is valid and can be used in whenever a Schema object is expected, for example, as a subcomponent of another schema:

definitions:
  Program:
    type: object
    properties:
      program_name:
        $ref: "#/definitions/program_name"

  # This becomes:
  # type: object
  # properties:
  #   program_name:
  #     type: string
  #     description: Unique string id

or as an operation body parameter or response schema:

paths:
  /something:
    post:
      summary: POSTs and returns a string
      parameters:
        - in: body
          name: program_name
          schema:
            $ref: "#/definitions/program_name"
      responses:
        "200":
           description: OK
           schema:
             $ref: "#/definitions/program_name"

However, simple parameters - path, query, header and form - do not use the schema keyword (they use type instead) and so they cannot reference schemas from definitions.

This will be changed in the next version, OpenAPI 3.0, where schema will be used for all parameter types.

Swagger Definition of primitive types

1 Answers