Forum Discussion

huhuang03's avatar
huhuang03
New Member
4 years ago

How can I use the ref examples in response

I have an response like this:

openapi: 3.0.0
info:
  description: |
    This is a sample Petstore server.  You can find
    out more about Swagger at
    [http://swagger.io](http://swagger.io) or on
    [irc.freenode.net, #swagger](http://swagger.io/irc/).
  version: "1.0.0"
  title: Swagger Petstore
  termsOfService: 'http://swagger.io/terms/'
  contact:
    email: apiteam@swagger.io
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
servers:
  # Added by API Auto Mocking Plugin
  - description: SwaggerHub API Auto Mocking
    url: https://virtserver.swaggerhub.com/huhuang03/Test_example/1.0.0
  - url: 'https://petstore.swagger.io/v2'
tags:
  - name: pet
    description: Everything about your Pets
    externalDocs:
      description: Find out more
      url: 'http://swagger.io'
paths:
  /order/list:
    get:
      tags:
        - order
      summary:  get orders by serach(current not search)
      operationId: placeOrder
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GJOrders'
externalDocs:
  description: Find out more about Swagger
  url: 'http://swagger.io'
components:
  schemas:
    GJ:
      type: object
      required:
        - msg
        - code
      properties:
        msg:
          type: string
          default: 'ok'
        code:
          type: integer
          default: 0
    GJOrders:
      allOf:
        - $ref: '#/components/schemas/GJ'
        - type: object
          properties:
            data:
              type: object
              properties:
                list: 
                  type: array
                  items:
                    $ref: '#/components/schemas/Order'
                  minItems: 10
                  maxItems: 10
                  example:
                  - $ref: '#/components/examples/Order'
                  - img: 'https://gimg2.baidu.com/image_search/src=http%3A%2F%2Fi2.hdslb.com%2Fbfs%2Farchive%2Fd1cfb9e8a3d3c34e8e76f15ea1aff3055e2aab9f.jpg&refer=http%3A%2F%2Fi2.hdslb.com&app=2002&size=f9999,10000&q=a80&n=0&g=0n&fmt=jpeg?sec=1630136171&t=15e975a22b21e8c3fd9d8f4fd73cc884'
                    price: '200'
                    category: '女装-上衣'
                    mianliao: '针织面料'
                    date: '2021-7-8'
    Order:
      type: object
      properties:
        img:
          type: string
          default: "https://gimg2.baidu.com/image_search/src=http%3A%2F%2Fi2.hdslb.com%2Fbfs%2Farchive%2Fd1cfb9e8a3d3c34e8e76f15ea1aff3055e2aab9f.jpg&refer=http%3A%2F%2Fi2.hdslb.com&app=2002&size=f9999,10000&q=a80&n=0&g=0n&fmt=jpeg?sec=1630136171&t=15e975a22b21e8c3fd9d8f4fd73cc884"
        price:
          type: string
          default: 200
        category:
          type: string
          default: '女装-上衣'
        mianliao:
          type: string
          default: '针织面料'
        date:
          type: string
          default: '2021-708'
          
  examples:
    Order:
      value:
        img: 'https://gimg2.baidu.com/image_search/src=http%3A%2F%2Fi2.hdslb.com%2Fbfs%2Farchive%2Fd1cfb9e8a3d3c34e8e76f15ea1aff3055e2aab9f.jpg&refer=http%3A%2F%2Fi2.hdslb.com&app=2002&size=f9999,10000&q=a80&n=0&g=0n&fmt=jpeg?sec=1630136171&t=15e975a22b21e8c3fd9d8f4fd73cc884'
        price: '200'
        category: '女装-上衣'
        mianliao: '针织面料'
        date: '2021-7-8'

 

The key code is L73:

- $ref: '#/components/examples/Order'

It's not work. If I want use examples in response. Can? and How?

 

Swagger Codegen
Swagger Editor
  • ponelat's avatar
    ponelat
    Staff
    4 years ago

    So examples in responses are supported, but $refs _within_ examples are not allowed as it isn't possible to distinguish between the example itself and the special keywords (like $ref).

     

    See bottom of the https://swagger.io/docs/specification/2-0/adding-examples/?sbsearch=Examples page.

     

    However, as for examples in responses... here is a quick sample:

     

    openapi: 3.0.3
info:
  title: Examples
  version: 1.2.3
  description: Using examples with $refs in responses.
  
paths:
  /foos:
    get:
      description: Get Foos
      responses:
        '200':
          description: A list of Foos
          content:
            application/json:
              examples:
                FirstExample: 
                  $ref: '#/components/examples/SomeExample'
components:
  examples:
    SomeExample:
      value:
      - one
      - two