Skip to main content

Appendix 1. Comparison with OpenAPI (Swagger)

Example 1.2. The simplest schema​

JSight 0.3OpenAPI 3.0.1 (Swagger)
JSIGHT 0.3
 
GET /cats/{id}
  200
    {
      "id"  : 123,
      "name": "Tom"
    }
openapi: 3.0.1
paths:
  /cats/{id}:
    get:
      parameters:
      - name: id
        in: path
        required: true
        schema: {}
      responses:
        200:
          content:
            application/json:
              schema:
                required: [id, name]
                type: object
                properties:
                  id:
                    type: integer
                    example: 123
                  name:
                    type: string
                    example: "Tom"

Example 1.3. Schema with rules​

JSight 0.3OpenAPI 3.0.1 (Swagger)
JSIGHT 0.3
 
GET /cats/{id}
  200
  {
      "id"  : 123,            // {min: 0}
      "name": "Tom",          // {maxLength: 120}
      "size": "L",            // {enum: ["S", "M", "L"]}
      "email": "tom@cats.com" /* {type: "email", 
                                  optional: true} */
  }
openapi: 3.0.1
paths:
  /cats/{id}:
    get:
      parameters:
      - name: id
        in: path
        required: true
        schema: {}
      responses:
        200:
          content:
            application/json:
              schema:
                required: [id, name, size]
                type: object
                properties:
                  id:
                    type: integer
                    minimum: 0
                    example: 123
                  name:
                    type: string
                    maxLength: 120
                    example: "Tom"
                  size:
                    type: string
                    example: "L"
                    enum: ["S", "M", "L"]
                  email:
                    type: string
                    format: email
                    example: "tom@cats.com"

Example 4.4. User types​

JSight 0.3OpenAPI 3.0.1 (Swagger)
TYPE @cat
{
  "id"     : @catId,
  "name"   : "Tom",
  "friends": [@cat]
}
 
TYPE @catId
  "CAT-123" // {regex: "^CAT-\\d+$"}
components:
  schemas:
    cat:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/catId'
        name:
          type: string
          example: "Tom"
        friends:
          type: array
          items:
            $ref: '#/components/schemas/cat'
 
    catId:
      type: string
      pattern: "^CAT-\\d+$"
      example: "CAT-123"

Example 5.2. Directive Query (extended example)​

JSight 0.3OpenAPI 3.0.1 (Swagger)
JSIGHT 0.3
 
GET /cats // Get a paged list of cats.
 
  Query "page=1&per_page=50"
    {
      "page": 1,     //                    Page number.
      "per_page": 50 // {optional: true} - Page size.
    }
 
  200 [@cat] // Successful response.
 
TYPE @cat // Type “Cat”.
  {
    "id"  : 123,
    "name": "Tom"
  }
openapi: 3.0.1
paths:
  /cats:
    get:
      summary: Get a paged list of cats.
      parameters:
      - name: page
        in: query
        description: Page number..
        required: true
        schema:
          type: integer
          example: 1
      - name: per_page
        in: query
        description: Page size.
        schema:
          type: integer
          example: 50
      responses:
        200:
          description: "Successful response."
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/cat'
components:
  schemas:
    cat:
      description: Type “Cat”.
      type: object
      properties:
        id:
          type: integer
          example: 123
        name:
          type: string
          example: "Tom"