From 917b6e0105811788614cbcebdf9ac6c116c63aae Mon Sep 17 00:00:00 2001
From: William Cheng <wing328hk@gmail.com>
Date: Tue, 29 May 2018 00:35:37 +0800
Subject: [PATCH] Add a section about body parameter name (#170)

---
 docs/migration-from-swagger-codegen.md | 59 ++++++++++++++++++++++++++
 1 file changed, 59 insertions(+)

diff --git a/docs/migration-from-swagger-codegen.md b/docs/migration-from-swagger-codegen.md
index 162766cd9f..303715f23c 100644
--- a/docs/migration-from-swagger-codegen.md
+++ b/docs/migration-from-swagger-codegen.md
@@ -166,5 +166,64 @@ If you have extended some generators in your project, and you are looking for a
 
 Example: `org.openapitools.codegen.DefaultGenerator`
 
+### Body parameter name
+
+In OpenAPI spec v3, there's no body parameter, which is replaced by [Request Body Object](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md#request-body-object). The parameter name for Request Body is named automatically based on the model name (e.g. User). To control how the "Request Body" parmaeter is named, please add the vendor extension `x-codegen-request-body-name` to the operation:
+
+OpenAPI Spec v3:
+```
+paths:
+  /pet:
+    post:
+      tags:
+        - pet
+      summary: Add a new pet to the store
+      description: ''
+      operationId: addPet
+      x-codegen-request-body-name: new_body_name
+      responses:
+        '405':
+          description: Invalid input
+      security:
+        - petstore_auth:
+            - 'write:pets'
+            - 'read:pets'
+      requestBody:
+        $ref: '#/components/requestBodies/Pet'
+```
+
+OpenAPI Spec v2:
+```
+paths:
+  /pet:
+    post:
+      tags:
+        - pet
+      summary: Add a new pet to the store
+      description: ''
+      operationId: addPet
+      x-codegen-request-body-name: new_body_name
+      consumes:
+        - application/json
+        - application/xml
+      produces:
+        - application/xml
+        - application/json
+      parameters:
+        - in: body
+          name: body
+          description: Pet object that needs to be added to the store
+          required: true
+          schema:
+            $ref: '#/definitions/Pet'
+      responses:
+        '405':
+          description: Invalid input
+      security:
+        - petstore_auth:
+            - 'write:pets'
+            - 'read:pets'
+```
+If your API client is using named parameters in the function call (e.g. Perl required & optional parameters, Ruby optional parameters), you will need to add `x-codegen-request-body-name` to the spec to restore the original body parameter name.
 
 [Back to OpenAPI-Generator's README page](../README.md)