Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

Swagger 2.0: How to declare a definition property of type model?

I want to declare a definition property of type model in Swagger 2.0

Is this definition correct? (specially the type: StatusObject part)

definitions:
  MyObject:
    type: "object"
    properties:
      id:
        type: "number"
      country:
        type: "string"
      status:
        type: StatusObject
  StatusObject:
    type: "object"
    properties:
      code:
        type: "number"
      shortMessage:
        type: "string"
      message:
        type: "string"

Thanks!

like image 663
JAM Avatar asked Sep 18 '14 15:09

JAM


People also ask

How do you write description in Swagger?

Add Description to Methods and Parameters. @ApiOperation defines the properties of an API method. We added a name to the operation using the value property, and a description using the notes property. @ApiResponses is used to override the default messages that accompany the response codes.

What is a Swagger definition file?

Swagger™ is a project used to describe and document RESTful APIs. The Swagger specification defines a set of files required to describe such an API. These files can then be used by the Swagger-UI project to display the API and Swagger-Codegen to generate clients in various languages.

What are the formats supported by OpenAPI Swagger for their definitions?

Format. An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.


2 Answers

In Swagger 2.0:

definitions:
  MyObject:
    properties:
     id:
      type: "number"
     country:
      type: "string"
     status:
      $ref: "#/definitions/StatusObject"
  StatusObject:
   properties:
    code:
     type: "number"
    shortMessage:
     type: "string"
    message:
     type: "string"
like image 165
Etienne Avatar answered Oct 23 '22 20:10

Etienne


Referring to other models/definitions is done using "$ref".

The above snippet should look like this:

definitions:
  MyObject:
    type: "object"
    properties:
      id:
        type: "number"
      country:
        type: "string"
      status:
        $ref: StatusObject
  StatusObject:
    type: "object"
    properties:
      code:
        type: "number"
      shortMessage:
        type: "string"
      message:
        type: "string"

Another comment - you're using "number" as the type for id and code. "number" can also have a decimal point which I'm not sure you want (especially for id). If you want whole numbers only, consider using "integer".

like image 36
Ron Avatar answered Oct 23 '22 20:10

Ron