#14141 Add externalDocs to @operation to the JavaSpring generator (#1…

…4177) * #14141 Add externalDocs to @operation to the JavaSpring generator * #14141 Add externalDocs to @operation to the JavaSpring generator : fix mustache template with #hasExternalDocs * #14141 Add externalDocs to @operation to the JavaSpring generator: fix indentation * #14141 Add externalDocs to @operation to the JavaSpring generator: fix carriage return * #14141 Add externalDocs to @operation to the JavaSpring generator: regenerate the spring-boot-oas3.yaml sample * #14141 Add externalDocs to @operation to the JavaSpring generator: generate-samples.sh * #14141 Add externalDocs to @operation to the JavaSpring generator: remove hasExternalDocs * Fix ExternalDocumentation import generation and order * #14141 Add externalDocs to @operation to the JavaSpring generator: generate-samples.sh
OpenAPITools · Jan 4, 2023 · 917892d · 917892d
1 parent 3dd313d
commit 917892d
Show file tree

Hide file tree

Showing 106 changed files with 222 additions and 6 deletions.
diff --git a/modules/openapi-generator/src/main/resources/JavaSpring/api.mustache b/modules/openapi-generator/src/main/resources/JavaSpring/api.mustache
@@ -8,6 +8,7 @@ package {{package}};
 {{#imports}}import {{import}};
 {{/imports}}
 {{#swagger2AnnotationLibrary}}
+import io.swagger.v3.oas.annotations.ExternalDocumentation;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.Parameters;
@@ -160,7 +161,8 @@ public interface {{classname}} {
             {{#authMethods}}
             @SecurityRequirement(name = "{{name}}"{{#isOAuth}}, scopes={ {{#scopes}}"{{scope}}"{{^-last}}, {{/-last}}{{/scopes}} }{{/isOAuth}}){{^-last}},{{/-last}}
             {{/authMethods}}
-        }{{/hasAuthMethods}}
+        }{{/hasAuthMethods}}{{#externalDocs}},
+        externalDocs = @ExternalDocumentation(description = "{{externalDocs.description}}", url = "{{externalDocs.url}}"){{/externalDocs}}
     )
     {{/swagger2AnnotationLibrary}}
     {{#swagger1AnnotationLibrary}}

diff --git a/...enapi-generator/src/test/java/org/openapitools/codegen/java/spring/SpringCodegenTest.java b/...enapi-generator/src/test/java/org/openapitools/codegen/java/spring/SpringCodegenTest.java
@@ -1243,6 +1243,48 @@ public void shouldPurAdditionalModelTypesOverAllModels() throws IOException {
         }
     }
 
+    @Test
+    public void shouldGenerateExternalDocs() throws IOException {
+        File output = Files.createTempDirectory("test").toFile().getCanonicalFile();
+        output.deleteOnExit();
+
+        OpenAPI openAPI = new OpenAPIParser()
+            .readLocation("src/test/resources/3_0/petstore.yaml", null, new ParseOptions()).getOpenAPI();
+        SpringCodegen codegen = new SpringCodegen();
+        codegen.setLibrary(SPRING_BOOT);
+        codegen.setOutputDir(output.getAbsolutePath());
+        codegen.additionalProperties().put(SpringCodegen.USE_TAGS, "true");
+        codegen.additionalProperties().put(BeanValidationFeatures.USE_BEANVALIDATION, "true");
+
+        ClientOptInput input = new ClientOptInput()
+            .openAPI(openAPI)
+            .config(codegen);
+
+        DefaultGenerator generator = new DefaultGenerator();
+        generator.setGeneratorPropertyDefault(CodegenConstants.MODELS, "false");
+        generator.setGeneratorPropertyDefault(CodegenConstants.MODEL_TESTS, "false");
+        generator.setGeneratorPropertyDefault(CodegenConstants.MODEL_DOCS, "false");
+        generator.setGeneratorPropertyDefault(CodegenConstants.APIS, "true");
+        generator.setGeneratorPropertyDefault(CodegenConstants.SUPPORTING_FILES, "false");
+
+        Map<String, File> files = generator.opts(input).generate().stream()
+            .collect(Collectors.toMap(File::getName, Function.identity()));
+
+        JavaFileAssert.assertThat(files.get("PetApi.java"))
+            .printFileContent()
+            .hasImports("io.swagger.v3.oas.annotations.ExternalDocumentation")
+            .assertMethod("updatePet")
+            .assertMethodAnnotations()
+            .containsWithName("Operation")
+            .containsWithNameAndAttributes("Operation",
+                ImmutableMap.of(
+                    "operationId", "\"updatePet\"",
+                    //"security", "{ @SecurityRequirement(name = \"petstore_auth\", scopes = { \"write:pets\", \"read:pets\" }) }",
+                    "externalDocs", "@ExternalDocumentation(description = \"API documentation for the updatePet operation\", url = \"http://petstore.swagger.io/v2/doc/updatePet\")"
+                )
+                );
+    }
+
     @Test
     public void testHandleDefaultValue_issue8535() throws Exception {
         Map<String, Object> additionalProperties = new HashMap<>();

diff --git a/modules/openapi-generator/src/test/resources/3_0/petstore.yaml b/modules/openapi-generator/src/test/resources/3_0/petstore.yaml
@@ -49,6 +49,9 @@ paths:
       summary: Update an existing pet
       description: ''
       operationId: updatePet
+      externalDocs:
+        url: "http://petstore.swagger.io/v2/doc/updatePet"
+        description: "API documentation for the updatePet operation"
       responses:
         '200':
           description: successful operation

diff --git a/samples/client/petstore/java/okhttp-gson-swagger1/api/openapi.yaml b/samples/client/petstore/java/okhttp-gson-swagger1/api/openapi.yaml
@@ -49,6 +49,9 @@ paths:
       x-accepts: application/json
     put:
       description: ""
+      externalDocs:
+        description: API documentation for the updatePet operation
+        url: http://petstore.swagger.io/v2/doc/updatePet
       operationId: updatePet
       requestBody:
         $ref: '#/components/requestBodies/Pet'

diff --git a/.../petstore/java/okhttp-gson-swagger1/src/main/java/org/openapitools/client/api/PetApi.java b/.../petstore/java/okhttp-gson-swagger1/src/main/java/org/openapitools/client/api/PetApi.java
@@ -747,6 +747,8 @@ public okhttp3.Call getPetByIdAsync(Long petId, final ApiCallback<Pet> _callback
         <tr><td> 404 </td><td> Pet not found </td><td>  -  </td></tr>
         <tr><td> 405 </td><td> Validation exception </td><td>  -  </td></tr>
      </table>
+     * API documentation for the updatePet operation
+     * @see <a href="http://petstore.swagger.io/v2/doc/updatePet">Update an existing pet Documentation</a>
      */
     public okhttp3.Call updatePetCall(Pet pet, final ApiCallback _callback) throws ApiException {
         String basePath = null;
@@ -820,6 +822,8 @@ private okhttp3.Call updatePetValidateBeforeCall(Pet pet, final ApiCallback _cal
         <tr><td> 404 </td><td> Pet not found </td><td>  -  </td></tr>
         <tr><td> 405 </td><td> Validation exception </td><td>  -  </td></tr>
      </table>
+     * API documentation for the updatePet operation
+     * @see <a href="http://petstore.swagger.io/v2/doc/updatePet">Update an existing pet Documentation</a>
      */
     public Pet updatePet(Pet pet) throws ApiException {
         ApiResponse<Pet> localVarResp = updatePetWithHttpInfo(pet);
@@ -840,6 +844,8 @@ public Pet updatePet(Pet pet) throws ApiException {
         <tr><td> 404 </td><td> Pet not found </td><td>  -  </td></tr>
         <tr><td> 405 </td><td> Validation exception </td><td>  -  </td></tr>
      </table>
+     * API documentation for the updatePet operation
+     * @see <a href="http://petstore.swagger.io/v2/doc/updatePet">Update an existing pet Documentation</a>
      */
     public ApiResponse<Pet> updatePetWithHttpInfo(Pet pet) throws ApiException {
         okhttp3.Call localVarCall = updatePetValidateBeforeCall(pet, null);
@@ -862,6 +868,8 @@ public ApiResponse<Pet> updatePetWithHttpInfo(Pet pet) throws ApiException {
         <tr><td> 404 </td><td> Pet not found </td><td>  -  </td></tr>
         <tr><td> 405 </td><td> Validation exception </td><td>  -  </td></tr>
      </table>
+     * API documentation for the updatePet operation
+     * @see <a href="http://petstore.swagger.io/v2/doc/updatePet">Update an existing pet Documentation</a>
      */
     public okhttp3.Call updatePetAsync(Pet pet, final ApiCallback<Pet> _callback) throws ApiException {
 

diff --git a/samples/client/petstore/java/resttemplate-swagger1/api/openapi.yaml b/samples/client/petstore/java/resttemplate-swagger1/api/openapi.yaml
@@ -49,6 +49,9 @@ paths:
       x-accepts: application/json
     put:
       description: ""
+      externalDocs:
+        description: API documentation for the updatePet operation
+        url: http://petstore.swagger.io/v2/doc/updatePet
       operationId: updatePet
       requestBody:
         $ref: '#/components/requestBodies/Pet'

diff --git a/...petstore/java/resttemplate-swagger1/src/main/java/org/openapitools/client/api/PetApi.java b/...petstore/java/resttemplate-swagger1/src/main/java/org/openapitools/client/api/PetApi.java
@@ -317,6 +317,8 @@ public ResponseEntity<Pet> getPetByIdWithHttpInfo(Long petId) throws RestClientE
      * @param pet Pet object that needs to be added to the store (required)
      * @return Pet
      * @throws RestClientException if an error occurs while attempting to invoke the API
+     * API documentation for the updatePet operation
+     * @see <a href="http://petstore.swagger.io/v2/doc/updatePet">Update an existing pet Documentation</a>
      */
     public Pet updatePet(Pet pet) throws RestClientException {
         return updatePetWithHttpInfo(pet).getBody();
@@ -332,6 +334,8 @@ public Pet updatePet(Pet pet) throws RestClientException {
      * @param pet Pet object that needs to be added to the store (required)
      * @return ResponseEntity&lt;Pet&gt;
      * @throws RestClientException if an error occurs while attempting to invoke the API
+     * API documentation for the updatePet operation
+     * @see <a href="http://petstore.swagger.io/v2/doc/updatePet">Update an existing pet Documentation</a>
      */
     public ResponseEntity<Pet> updatePetWithHttpInfo(Pet pet) throws RestClientException {
         Object localVarPostBody = pet;

diff --git a/...nt/petstore/spring-cloud-feign-without-url/src/main/java/org/openapitools/api/PetApi.java b/...nt/petstore/spring-cloud-feign-without-url/src/main/java/org/openapitools/api/PetApi.java
@@ -212,6 +212,8 @@ ResponseEntity<Pet> getPetById(
      *         or Invalid ID supplied (status code 400)
      *         or Pet not found (status code 404)
      *         or Validation exception (status code 405)
+     * API documentation for the updatePet operation
+     * @see <a href="http://petstore.swagger.io/v2/doc/updatePet">Update an existing pet Documentation</a>
      */
     @ApiOperation(
         tags = { "pet" },

diff --git a/samples/client/petstore/spring-cloud/src/main/java/org/openapitools/api/PetApi.java b/samples/client/petstore/spring-cloud/src/main/java/org/openapitools/api/PetApi.java
@@ -212,6 +212,8 @@ ResponseEntity<Pet> getPetById(
      *         or Invalid ID supplied (status code 400)
      *         or Pet not found (status code 404)
      *         or Validation exception (status code 405)
+     * API documentation for the updatePet operation
+     * @see <a href="http://petstore.swagger.io/v2/doc/updatePet">Update an existing pet Documentation</a>
      */
     @ApiOperation(
         tags = { "pet" },

diff --git a/samples/openapi3/client/petstore/java/jersey2-java8-swagger1/api/openapi.yaml b/samples/openapi3/client/petstore/java/jersey2-java8-swagger1/api/openapi.yaml
@@ -49,6 +49,9 @@ paths:
       x-accepts: application/json
     put:
       description: ""
+      externalDocs:
+        description: API documentation for the updatePet operation
+        url: http://petstore.swagger.io/v2/doc/updatePet
       operationId: updatePet
       requestBody:
         $ref: '#/components/requestBodies/Pet'

diff --git a/...etstore/java/jersey2-java8-swagger1/src/main/java/org/openapitools/client/api/PetApi.java b/...etstore/java/jersey2-java8-swagger1/src/main/java/org/openapitools/client/api/PetApi.java
@@ -415,6 +415,8 @@ public ApiResponse<Pet> getPetByIdWithHttpInfo(Long petId) throws ApiException {
        <tr><td> 404 </td><td> Pet not found </td><td>  -  </td></tr>
        <tr><td> 405 </td><td> Validation exception </td><td>  -  </td></tr>
      </table>
+   * API documentation for the updatePet operation
+   * @see <a href="http://petstore.swagger.io/v2/doc/updatePet">Update an existing pet Documentation</a>
    */
   public Pet updatePet(Pet pet) throws ApiException {
     return updatePetWithHttpInfo(pet).getData();
@@ -434,6 +436,8 @@ public Pet updatePet(Pet pet) throws ApiException {
        <tr><td> 404 </td><td> Pet not found </td><td>  -  </td></tr>
        <tr><td> 405 </td><td> Validation exception </td><td>  -  </td></tr>
      </table>
+   * API documentation for the updatePet operation
+   * @see <a href="http://petstore.swagger.io/v2/doc/updatePet">Update an existing pet Documentation</a>
    */
   public ApiResponse<Pet> updatePetWithHttpInfo(Pet pet) throws ApiException {
     Object localVarPostBody = pet;

diff --git a/...es/openapi3/client/petstore/spring-cloud-3/src/main/java/org/openapitools/api/PetApi.java b/...es/openapi3/client/petstore/spring-cloud-3/src/main/java/org/openapitools/api/PetApi.java
@@ -7,6 +7,7 @@
 
 import org.openapitools.model.ModelApiResponse;
 import org.openapitools.model.Pet;
+import io.swagger.v3.oas.annotations.ExternalDocumentation;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.Parameters;
@@ -216,6 +217,8 @@ ResponseEntity<Pet> getPetById(
      *         or Invalid ID supplied (status code 400)
      *         or Pet not found (status code 404)
      *         or Validation exception (status code 405)
+     * API documentation for the updatePet operation
+     * @see <a href="http://petstore.swagger.io/v2/doc/updatePet">Update an existing pet Documentation</a>
      */
     @Operation(
         operationId = "updatePet",
@@ -233,7 +236,8 @@ ResponseEntity<Pet> getPetById(
         },
         security = {
             @SecurityRequirement(name = "petstore_auth", scopes={ "write:pets", "read:pets" })
-        }
+        },
+        externalDocs = @ExternalDocumentation(description = "API documentation for the updatePet operation", url = "http://petstore.swagger.io/v2/doc/updatePet")
     )
     @RequestMapping(
         method = RequestMethod.PUT,

diff --git a/.../openapi3/client/petstore/spring-cloud-3/src/main/java/org/openapitools/api/StoreApi.java b/.../openapi3/client/petstore/spring-cloud-3/src/main/java/org/openapitools/api/StoreApi.java
@@ -7,6 +7,7 @@
 
 import java.util.Map;
 import org.openapitools.model.Order;
+import io.swagger.v3.oas.annotations.ExternalDocumentation;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.Parameters;

diff --git a/...s/openapi3/client/petstore/spring-cloud-3/src/main/java/org/openapitools/api/UserApi.java b/...s/openapi3/client/petstore/spring-cloud-3/src/main/java/org/openapitools/api/UserApi.java
@@ -8,6 +8,7 @@
 import java.util.List;
 import java.time.OffsetDateTime;
 import org.openapitools.model.User;
+import io.swagger.v3.oas.annotations.ExternalDocumentation;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.Parameters;

diff --git a/...penapi3/client/petstore/spring-cloud-async/src/main/java/org/openapitools/api/PetApi.java b/...penapi3/client/petstore/spring-cloud-async/src/main/java/org/openapitools/api/PetApi.java
@@ -7,6 +7,7 @@
 
 import org.openapitools.model.ModelApiResponse;
 import org.openapitools.model.Pet;
+import io.swagger.v3.oas.annotations.ExternalDocumentation;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.Parameters;

diff --git a/...napi3/client/petstore/spring-cloud-async/src/main/java/org/openapitools/api/StoreApi.java b/...napi3/client/petstore/spring-cloud-async/src/main/java/org/openapitools/api/StoreApi.java
@@ -7,6 +7,7 @@
 
 import java.util.Map;
 import org.openapitools.model.Order;
+import io.swagger.v3.oas.annotations.ExternalDocumentation;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.Parameters;

diff --git a/...enapi3/client/petstore/spring-cloud-async/src/main/java/org/openapitools/api/UserApi.java b/...enapi3/client/petstore/spring-cloud-async/src/main/java/org/openapitools/api/UserApi.java
@@ -8,6 +8,7 @@
 import java.util.List;
 import java.time.OffsetDateTime;
 import org.openapitools.model.User;
+import io.swagger.v3.oas.annotations.ExternalDocumentation;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.Parameters;

diff --git a/...client/petstore/spring-cloud-date-time/src/main/java/org/openapitools/api/DefaultApi.java b/...client/petstore/spring-cloud-date-time/src/main/java/org/openapitools/api/DefaultApi.java
@@ -8,6 +8,7 @@
 import org.springframework.format.annotation.DateTimeFormat;
 import java.time.LocalDate;
 import java.time.OffsetDateTime;
+import io.swagger.v3.oas.annotations.ExternalDocumentation;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.Parameters;

diff --git a/...petstore/spring-cloud-oas3-fakeapi/src/main/java/org/openapitools/api/AnotherFakeApi.java b/...petstore/spring-cloud-oas3-fakeapi/src/main/java/org/openapitools/api/AnotherFakeApi.java
@@ -6,6 +6,7 @@
 package org.openapitools.api;
 
 import org.openapitools.model.Client;
+import io.swagger.v3.oas.annotations.ExternalDocumentation;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.Parameters;

diff --git a/...client/petstore/spring-cloud-oas3-fakeapi/src/main/java/org/openapitools/api/FakeApi.java b/...client/petstore/spring-cloud-oas3-fakeapi/src/main/java/org/openapitools/api/FakeApi.java
@@ -15,6 +15,7 @@
 import org.openapitools.model.OuterComposite;
 import org.openapitools.model.User;
 import org.openapitools.model.XmlItem;
+import io.swagger.v3.oas.annotations.ExternalDocumentation;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.Parameters;

diff --git a/...spring-cloud-oas3-fakeapi/src/main/java/org/openapitools/api/FakeClassnameTags123Api.java b/...spring-cloud-oas3-fakeapi/src/main/java/org/openapitools/api/FakeClassnameTags123Api.java
@@ -6,6 +6,7 @@
 package org.openapitools.api;
 
 import org.openapitools.model.Client;
+import io.swagger.v3.oas.annotations.ExternalDocumentation;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.Parameters;

diff --git a/.../client/petstore/spring-cloud-oas3-fakeapi/src/main/java/org/openapitools/api/PetApi.java b/.../client/petstore/spring-cloud-oas3-fakeapi/src/main/java/org/openapitools/api/PetApi.java
@@ -8,6 +8,7 @@
 import org.openapitools.model.ModelApiResponse;
 import org.openapitools.model.Pet;
 import java.util.Set;
+import io.swagger.v3.oas.annotations.ExternalDocumentation;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.Parameters;

diff --git a/...lient/petstore/spring-cloud-oas3-fakeapi/src/main/java/org/openapitools/api/StoreApi.java b/...lient/petstore/spring-cloud-oas3-fakeapi/src/main/java/org/openapitools/api/StoreApi.java
@@ -7,6 +7,7 @@
 
 import java.util.Map;
 import org.openapitools.model.Order;
+import io.swagger.v3.oas.annotations.ExternalDocumentation;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.Parameters;

diff --git a/...client/petstore/spring-cloud-oas3-fakeapi/src/main/java/org/openapitools/api/UserApi.java b/...client/petstore/spring-cloud-oas3-fakeapi/src/main/java/org/openapitools/api/UserApi.java
@@ -8,6 +8,7 @@
 import java.util.List;
 import java.time.OffsetDateTime;
 import org.openapitools.model.User;
+import io.swagger.v3.oas.annotations.ExternalDocumentation;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.Parameters;

diff --git a/...ient/petstore/spring-cloud-spring-pageable/src/main/java/org/openapitools/api/PetApi.java b/...ient/petstore/spring-cloud-spring-pageable/src/main/java/org/openapitools/api/PetApi.java
@@ -9,6 +9,7 @@
 import org.springframework.data.domain.Pageable;
 import org.springdoc.api.annotations.ParameterObject;
 import org.openapitools.model.Pet;
+import io.swagger.v3.oas.annotations.ExternalDocumentation;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.Parameters;

diff --git a/...nt/petstore/spring-cloud-spring-pageable/src/main/java/org/openapitools/api/StoreApi.java b/...nt/petstore/spring-cloud-spring-pageable/src/main/java/org/openapitools/api/StoreApi.java
@@ -7,6 +7,7 @@
 
 import java.util.Map;
 import org.openapitools.model.Order;
+import io.swagger.v3.oas.annotations.ExternalDocumentation;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.Parameters;

diff --git a/...ent/petstore/spring-cloud-spring-pageable/src/main/java/org/openapitools/api/UserApi.java b/...ent/petstore/spring-cloud-spring-pageable/src/main/java/org/openapitools/api/UserApi.java
@@ -8,6 +8,7 @@
 import java.util.List;
 import java.time.OffsetDateTime;
 import org.openapitools.model.User;
+import io.swagger.v3.oas.annotations.ExternalDocumentation;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.Parameters;

diff --git a/samples/openapi3/client/petstore/spring-cloud/src/main/java/org/openapitools/api/PetApi.java b/samples/openapi3/client/petstore/spring-cloud/src/main/java/org/openapitools/api/PetApi.java
@@ -7,6 +7,7 @@
 
 import org.openapitools.model.ModelApiResponse;
 import org.openapitools.model.Pet;
+import io.swagger.v3.oas.annotations.ExternalDocumentation;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.Parameters;
@@ -216,6 +217,8 @@ ResponseEntity<Pet> getPetById(
      *         or Invalid ID supplied (status code 400)
      *         or Pet not found (status code 404)
      *         or Validation exception (status code 405)
+     * API documentation for the updatePet operation
+     * @see <a href="http://petstore.swagger.io/v2/doc/updatePet">Update an existing pet Documentation</a>
      */
     @Operation(
         operationId = "updatePet",
@@ -233,7 +236,8 @@ ResponseEntity<Pet> getPetById(
         },
         security = {
             @SecurityRequirement(name = "petstore_auth", scopes={ "write:pets", "read:pets" })
-        }
+        },
+        externalDocs = @ExternalDocumentation(description = "API documentation for the updatePet operation", url = "http://petstore.swagger.io/v2/doc/updatePet")
     )
     @RequestMapping(
         method = RequestMethod.PUT,

diff --git a/...es/openapi3/client/petstore/spring-cloud/src/main/java/org/openapitools/api/StoreApi.java b/...es/openapi3/client/petstore/spring-cloud/src/main/java/org/openapitools/api/StoreApi.java
@@ -7,6 +7,7 @@
 
 import java.util.Map;
 import org.openapitools.model.Order;
+import io.swagger.v3.oas.annotations.ExternalDocumentation;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.Parameters;

diff --git a/...les/openapi3/client/petstore/spring-cloud/src/main/java/org/openapitools/api/UserApi.java b/...les/openapi3/client/petstore/spring-cloud/src/main/java/org/openapitools/api/UserApi.java
@@ -8,6 +8,7 @@
 import java.util.List;
 import java.time.OffsetDateTime;
 import org.openapitools.model.User;
+import io.swagger.v3.oas.annotations.ExternalDocumentation;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.Parameters;

diff --git a/...tstore/spring-stubs-skip-default-interface/src/main/java/org/openapitools/api/PetApi.java b/...tstore/spring-stubs-skip-default-interface/src/main/java/org/openapitools/api/PetApi.java
@@ -7,6 +7,7 @@
 
 import org.openapitools.model.ModelApiResponse;
 import org.openapitools.model.Pet;
+import io.swagger.v3.oas.annotations.ExternalDocumentation;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.Parameter;
 import io.swagger.v3.oas.annotations.Parameters;