Swaggerhub returns predefined response, but server stub doesn't

Question

I have API yaml specification that defines what should be the response from each endpoint, e.g. I want that /version returns version1.0 as defined:

openapi: "3.0.3"
info:
  title: "TITLE"
  description: "DESCRIPTION"
  version: "1.0.0"
paths:
  /version:
    get:      
      description: "description"      
      responses:
        "200": 
          description: "description"
          content: 
            application/json:
              schema:
                $ref: '#/components/schemas/version'
components:
  schemas:
    version:
      type: object
      properties:
        version:
          type: string
      example:
        "version": "version1.0"

API server that runs on Swaggerhub works like expected, but e.g. python-flask server stub generated by Swaggerhub and run locally on my machine returns do some magic! for every endpoint and not the example provided in yaml. The same with server stubs generated using swagger-codegen and openapi-generator.

I am mainly interested in making it work for openapi-generator generated server stub.

score 0 · Accepted Answer · answered Dec 28 '21 at 15:00

This is working as expected.

The example tag is an OpenAPI tag to provide an example object or schema to your users to demonstrate the use of your APIs. The virtual service provided by SwaggerHub (virtserver) is able to interpret example value and return these values when you make API calls to virtualized service provided by SwaggerHub.

On the other hand, codegen may or may not handle example tags in the same way (it depends on the codegen template). I have two recommendations about how to go about resolving this:

Add the example return values yourself. The codegen is not meant to be a complete solution, it's meant to be a jumping off point for development. Once you've generated the code, implement and add in your own business logic.
Create your own codegen template. This is a popular option for anyone who needs Swagget codegen to do something that isn't currently supported: https://github.com/swagger-api/swagger-codegen/wiki/Building-your-own-Templates

Swaggerhub returns predefined response, but server stub doesn't

1 Answers1