Forum Discussion

dungreact's avatar
dungreact
Occasional Visitor
3 years ago

Help me validate my specification

Hi, I'm learning to write a specification with Swagger Editor. I'm considering it's wrong or not. please review it for me.

openapi: 3.0.1
info:
    title: NAshop
    description: 'This is NAshop document'
    contact:
        email: dungreact@gmail.com
    license:
        name: Apache 2.0
        url: http://www.apache.org/licenses/LICENSE-2.0.html
    version: 1.0.0
servers:
    - url: http://localhost:8080/api
      description: Development server
    - url: https://localhost:8080/api
      description: Development server with TLS Profile
tags:
    - name: product
      description: Everything about your products
paths:
    /product/findByStatus:
        get:
            tags:
                - product
            summary: Finds Product by status
            description: Multiple status values can be provided with comma separated strings
            operationId: findProductsByStatus
            parameters:
                - name: status
                  in: query
                  description: Status values that need to be considered for filter
                  required: true
                  style: form
                  explode: true
                  schema:
                      $ref: '#/components/schemas/ProductStatus'
            responses:
                200:
                    description: successful operation
                    content:
                        application/xml:
                            schema:
                                type: array
                                items:
                                    $ref: '#/components/schemas/Product'
                        application/json:
                            schema:
                                type: array
                                items:
                                    $ref: '#/components/schemas/Product'
                400:
                    description: Invalid status value
                    content: {}
            security:
                - jwt: []
                - basic: []
components:
    responses:
        Problem:
            description: error occurred - see status code and problem object for more information.
            content:
                'application/problem+json':
                    schema:
                        $ref: 'https://opensource.zalando.com/problem/schema.yaml#/Problem'
    schemas:
        ProductStatus:
            type: string
            enum:
                - available
                - unavailable
        Product:
            type: object
            required:
                - name
                - price
                - inventory
                - status
            properties:
                id:
                    type: integer
                    format: int64
                imageUrl:
                    type: string
                name:
                    type: string
                price:
                    type: number
                inventory:
                    type: number
                createAt:
                    type: string
                status:
                    $ref: '#/components/schemas/ProductStatus'
            xml:
                name: Product
    securitySchemes:
        jwt:
            type: http
            description: JWT Authentication
            scheme: bearer
            bearerFormat: JWT
        basic:
            type: http
            description: Basic Authentication
            scheme: basic

1 Reply

  • HKosova's avatar
    HKosova
    SmartBear Alumni (Retired)

    Looks good to me!

     

    I would suggest adding xml.name and xml.wrapped = true to the XML array response as additional serialization hints.

                        content:
                            application/xml:
                                schema:
                                    type: array
                                    items:
                                        $ref: '#/components/schemas/Product'
                                    xml:
                                      name: Products   # <---------
                                      wrapped: true    # <---------