postmanlabs / openapi-to-postman

Plugin for converting OpenAPI 3.0 specs to the Postman Collection (v2) format
Apache License 2.0
928 stars 200 forks source link

Add `Hybrid` option to parametersResolution #767

Closed dyadyaJora closed 5 months ago

dyadyaJora commented 1 year ago

Hello!

This PR is an attempt to fix disabling faking schema #240 in v2 interface. Today parametersResolution generates from schema (e.g. "") or from example (if example doesn't exist it generates some "lorem ipsum" stuff). I suggest to add new value Hybrid to parametersResolution in order to provide mode in which if example exists - use it, if not - use placeholder as in "Schema" mode instead of "lorem ipsum" because there are some case (like dates) where this replacement is not appropriate.

F.e.: with new mode for petstore spec we will have such generated bodies

with hybrid mode:

...
"body": "{\n  \"name\": \"doggie\",\n  \"photoUrls\": [\n    \"<string>\",\n    \"<string>\"\n  ],\n  \"id\": 10,\n  \"category\": {\n    \"id\": 1,\n    \"name\": \"Dogs\"\n  },\n  \"tags\": [\n    {\n      \"id\": \"<long>\",\n      \"name\": \"<string>\"\n    },\n    {\n      \"id\": \"<long>\",\n      \"name\": \"<string>\"\n    }\n  ],\n  \"status\": \"available\"\n}",
...

with example mode:

...
"body": "{\n  \"name\": \"doggie\",\n  \"photoUrls\": [\n    \"dolor tempor nostrud\",\n    \"sunt elit irure labore\"\n  ],\n  \"id\": 10,\n  \"category\": {\n    \"id\": 1,\n    \"name\": \"Dogs\"\n  },\n  \"tags\": [\n    {\n      \"id\": 95809042,\n      \"name\": \"ad aliquip\"\n    },\n    {\n      \"id\": 32265839,\n      \"name\": \"in cillum\"\n    }\n  ],\n  \"status\": \"sold\"\n}",
...

with schema mode:

...
"body": "{\n  \"name\": \"<string>\",\n  \"photoUrls\": [\n    \"<string>\",\n    \"<string>\"\n  ],\n  \"id\": \"<long>\",\n  \"category\": {\n    \"id\": \"<long>\",\n    \"name\": \"<string>\"\n  },\n  \"tags\": [\n    {\n      \"id\": \"<long>\",\n      \"name\": \"<string>\"\n    },\n    {\n      \"id\": \"<long>\",\n      \"name\": \"<string>\"\n    }\n  ],\n  \"status\": \"sold\"\n}",
...
openapi: 3.0.2
servers:
  - url: /v3
info:
  description: tmp
  version: 1.0.17
  title: Swagger Petstore - OpenAPI 3.0
  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'
tags:
  - name: pet
    description: Everything about your Pets
    externalDocs:
      description: Find out more
      url: 'http://swagger.io'
  - name: store
    description: Access to Petstore orders
    externalDocs:
      description: Find out more about our store
      url: 'http://swagger.io'
  - name: user
    description: Operations about user
paths:
  /pet:
    post:
      tags:
        - pet
      summary: Add a new pet to the store
      description: Add a new pet to the store
      operationId: addPet
      responses:
        '200':
          description: Successful operation
          content:
            application/xml:
              schema:
                $ref: '#/components/schemas/Pet'
            application/json:
              schema:
                $ref: '#/components/schemas/Pet'
        '405':
          description: Invalid input
      security:
        - petstore_auth:
            - 'write:pets'
            - 'read:pets'
      requestBody:
        description: Create a new pet in the store
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Pet'
          application/xml:
            schema:
              $ref: '#/components/schemas/Pet'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/Pet'
components:
  schemas:
    Category:
      x-swagger-router-model: io.swagger.petstore.model.Category
      properties:
        id:
          type: integer
          format: int64
          example: 1
        name:
          type: string
          example: Dogs
      xml:
        name: category
      type: object
    Tag:
      x-swagger-router-model: io.swagger.petstore.model.Tag
      properties:
        id:
          type: integer
          format: int64
        name:
          type: string
      xml:
        name: tag
      type: object
    Pet:
      x-swagger-router-model: io.swagger.petstore.model.Pet
      required:
        - name
        - photoUrls
      properties:
        id:
          type: integer
          format: int64
          example: 10
        name:
          type: string
          example: doggie
        category:
          $ref: '#/components/schemas/Category'
        photoUrls:
          type: array
          xml:
            wrapped: true
          items:
            type: string
            xml:
              name: photoUrl
        tags:
          type: array
          xml:
            wrapped: true
          items:
            $ref: '#/components/schemas/Tag'
            xml:
              name: tag
        status:
          type: string
          description: pet status in the store
          enum:
            - available
            - pending
            - sold
      xml:
        name: pet
      type: object
  securitySchemes:
    petstore_auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: 'https://petstore.swagger.io/oauth/authorize'
          scopes:
            'write:pets': modify pets in your account
            'read:pets': read your pets
    api_key:
      type: apiKey
      name: api_key
      in: header