fix(spec): update OAD to match core rules

.github/workflows/maven-pulls.yml

@@ -19,7 +19,7 @@ jobs:
         with:
           java-version: ${{ matrix.java }}
       - name: Cache local Maven repository
-        uses: actions/cache@v2
+        uses: actions/cache@v4
         with:
           path: ~/.m2/repository
           key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}

.github/workflows/maven.yml

@@ -22,7 +22,7 @@ jobs:
           server-username: MAVEN_USERNAME
           server-password: MAVEN_PASSWORD
       - name: Cache local Maven repository
-        uses: actions/cache@v2
+        uses: actions/cache@v4
         with:
           path: ~/.m2/repository
           key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }}

src/main/java/io/swagger/petstore/model/ApiResponse.java

@@ -35,7 +35,7 @@ public ApiResponse(int code, String message){
       setType("too busy");
       break;
     default:
-      setType("unknown");
+      setType("Unexpected error");
       break;
     }
     this.message = message;

src/main/java/io/swagger/petstore/model/Category.java

@@ -15,7 +15,7 @@ public class Category {
   private String name;
 
   @XmlElement(name = "id")
-  @Schema(example = "1")
+  @Schema(examples = {"1"})
   public long getId() {
     return id;
   }
@@ -25,7 +25,7 @@ public void setId(long id) {
   }
 
   @XmlElement(name = "name")
-  @Schema(example = "Dogs")
+  @Schema(examples = {"Dogs"})
   public String getName() {
     return name;
   }

src/main/java/io/swagger/petstore/model/Pet.java

@@ -30,7 +30,7 @@ public class Pet {
     private PetDetails petDetails;
 
     @XmlElement(name = "id")
-    @Schema(example = "10")
+    @Schema(examples = {"10"})
     public Long getId() {
         return id;
     }
@@ -49,7 +49,7 @@ public void setCategory(final Category category) {
     }
 
     @XmlElement(name = "name")
-    @Schema(requiredMode = Schema.RequiredMode.REQUIRED, example = "doggie")
+    @Schema(requiredMode = Schema.RequiredMode.REQUIRED, examples = {"doggie"})
     public String getName() {
         return name;
     }
@@ -102,7 +102,7 @@ public void setPetDetails(final PetDetails petDetails) {
 
     @XmlElement(name = "availableInstances")
     @Schema(
-            example = "7",
+            examples = {"7"},
             exclusiveMaximumValue = 10,
             exclusiveMinimumValue = 1,
             extensions = {

src/main/java/io/swagger/petstore/model/PetDetails.java

@@ -23,7 +23,7 @@ public class PetDetails {
     private String status;
 
     @XmlElement(name = "id")
-    @Schema(example = "10", $anchor = "pet_details_id")
+    @Schema(examples = {"10"}, $anchor = "pet_details_id")
     public long getId() {
         return id;
     }

src/main/java/io/swagger/petstore/resource/DefinitionResource.java

@@ -22,15 +22,15 @@
         info = @Info(
                 title = "Swagger Petstore - OpenAPI 3.1",
                 summary = "Pet Store 3.1",
-                version = "1.0.8-SNAPSHOT",
-                description = "This is a sample Pet Store Server based on the OpenAPI 3.1 specification.\nYou can find out more about\nSwagger at [http://swagger.io](http://swagger.io).",
-                termsOfService = "http://swagger.io/terms/",
+                version = "1.0.9-SNAPSHOT",
+                description = "This is a sample Pet Store Server based on the OpenAPI 3.1 specification.\nYou can find out more about\nSwagger at [https://swagger.io](https://swagger.io).",
+                termsOfService = "https://swagger.io/terms/",
                 contact = @Contact (
                         email = "apiteam@swagger.io"
                 ),
                 license = @License(
-                        name = "Apache 2.0 AND (MIT OR GPL-2.0-only)",
-                        identifier = "Apache-2.0 AND (MIT OR GPL-2.0-only)"
+                        name = "Apache 2.0",
+                        url = "https://www.apache.org/licenses/LICENSE-2.0.html"
                 ),
                 extensions = {@Extension(name = "", properties = {@ExtensionProperty(name = "x-namespace", value = "swagger")})}
         ),
@@ -41,7 +41,7 @@
         },
         externalDocs = @ExternalDocumentation(
                 description = "Find out more about Swagger",
-                url = "http://swagger.io"
+                url = "https://swagger.io"
         )
 )
 @Tags(
@@ -51,15 +51,15 @@
                         description = "Everything about your Pets",
                         externalDocs = @ExternalDocumentation(
                                 description = "Find out more",
-                                url = "http://swagger.io"
+                                url = "https://swagger.io"
                         )
                 ),
                 @Tag(
                         name = "store",
                         description = "Access to Petstore orders",
                         externalDocs = @ExternalDocumentation(
                                 description = "Find out more about our store",
-                                url = "http://swagger.io"
+                                url = "https://swagger.io"
                         )
                 ),
                 @Tag(
@@ -80,7 +80,7 @@
                                     @OAuthScope(name = "write:pets", description = "modify pets in your account"),
                                     @OAuthScope(name = "read:pets", description = "read your pets")
                             },
-                            authorizationUrl = "https://petstore3.swagger.io/oauth/authorize"
+                            authorizationUrl = "https://petstore31.swagger.io/oauth/authorize"
                         )
                     )
                 ),

src/main/java/io/swagger/petstore/resource/PetDetailsResource.java

@@ -26,7 +26,7 @@ public Response petDetails() {
                 "      \"type\": \"integer\",\n" +
                 "      \"format\": \"int64\",\n" +
                 "      \"$anchor\": \"pet_details_id\",\n" +
-                "      \"example\": 10\n" +
+                "      \"examples\": [10]\n" +
                 "    },\n" +
                 "    \"category\": {\n" +
                 "      \"$ref\": \"/api/v31/components/schemas/category\",\n" +

src/main/java/io/swagger/petstore/resource/PetResource.java

@@ -28,15 +28,15 @@
 
     @GET
     @Path("/{petId}")
-    @Operation(summary = "Find pet by ID",
+    @Operation(summary = "Find pet by it's identifier.",
             tags = {"pets"},
-            description = "Returns a pet when 0 < ID <= 10.  ID > 10 or nonintegers will simulate API error conditions",
+            description = "Returns a pet when 0 < ID <= 10.  ID > 10 or non-integers will simulate API error conditions.",
             security = {
                     @SecurityRequirement(name = "petstore_auth", scopes = {"write:pets", "read:pets"}),
                     @SecurityRequirement(name = "api_key", scopes = {})
             },
             responses = {
-                    @ApiResponse(description = "The pet", content = {
+                    @ApiResponse(responseCode = "200", description = "The pet", content = {
                             @Content(
                                     mediaType = "application/json",
                                     schema = @Schema(implementation = Pet.class, description = "A Pet in JSON format")
@@ -45,8 +45,10 @@
                                     mediaType = "application/xml",
                                     schema = @Schema(implementation = Pet.class, description = "A Pet in XML format")
                             )
-                    }), @ApiResponse(responseCode = "400", description = "Invalid ID supplied"),
-                    @ApiResponse(responseCode = "404", description = "Pet not found")
+                    }), 
+                    @ApiResponse(responseCode = "400", description = "Invalid ID supplied"),
+                    @ApiResponse(responseCode = "404", description = "Pet not found"),
+                    @ApiResponse(description = "Unexpected error")
             })
     public Response getPetById(
             @Parameter(
@@ -73,7 +75,7 @@
     }
 
     @POST
-    @Operation(summary = "Add a new pet to the store", description = "Add a new pet to the store",
+    @Operation(summary = "Add a new pet to the store.", description = "Add a new pet to the store.",
             tags = {"pet"},
             security = {
                     @SecurityRequirement(name = "petstore_auth", scopes = {"write:pets", "read:pets"})
@@ -86,23 +88,24 @@
                             content = {
                                     @Content(
                                             mediaType = "application/xml",
-                                            schema = @Schema(
+                                            schema = @Schema( implementation = Pet.class,
                                                     accessMode = Schema.AccessMode.READ_ONLY,
                                                     description = "A Pet in XML Format"
                                             )
                                     ),
                                     @Content(
                                             mediaType = "application/json",
-                                            schema = @Schema(
-                                                    accessMode = Schema.AccessMode.READ_ONLY,
-                                                    description = "A Pet in JSON Format"
-                                            )
+                                            schema = @Schema( implementation = Pet.class, 
+                                                accessMode = Schema.AccessMode.READ_ONLY,
+                                                description = "A Pet in JSON format"
+                                                )
                                     )
                             }
                     ),
-                    @ApiResponse(responseCode = "405", description = "Invalid input")})
+                    @ApiResponse(responseCode = "405", description = "Invalid input"),
+                    @ApiResponse(description = "Unexpected error")})
     @Consumes({"application/json", "application/xml"})
-    public Pet addPet(
+    public Response addPet(
             @RequestBody(
                     description = "Create a new pet in the store",
                     required = true,
@@ -127,11 +130,11 @@
                     }
             ) Pet pet) {
         petData.addPet(pet);
-        return pet;
+        return Response.ok().entity(pet).build();
     }
 
     @PUT
-    @Operation(summary = "Update an existing pet", description = "Update an existing pet by Id",
+    @Operation(summary = "Update an existing pet.", description = "Update an existing pet by Id.",
             tags = {"pet"},
             security = {
                     @SecurityRequirement(name = "petstore_auth", scopes = {"write:pets", "read:pets"})
@@ -144,25 +147,29 @@
                             content = {
                                     @Content(
                                             mediaType = "application/xml",
-                                            schema = @Schema(
-                                                    accessMode = Schema.AccessMode.READ_ONLY,
-                                                    description = "A Pet in XML Format"
+                                            schema = @Schema( 
+                                                implementation = Pet.class,
+                                                accessMode = Schema.AccessMode.READ_ONLY,
+                                                description = "A Pet in XML Format"
                                             )
                                     ),
                                     @Content(
                                             mediaType = "application/json",
                                             schema = @Schema(
-                                                    accessMode = Schema.AccessMode.READ_ONLY,
-                                                    description = "A Pet in JSON Format"
+                                                implementation = Pet.class, 
+                                                accessMode = Schema.AccessMode.READ_ONLY,
+                                                description = "A Pet in JSON Format"
                                             )
                                     )
                             }
                     ),
                     @ApiResponse(responseCode = "400", description = "Invalid ID supplied"),
                     @ApiResponse(responseCode = "404", description = "Pet not found"),
-                    @ApiResponse(responseCode = "405", description = "Validation exception")})
+                    @ApiResponse(responseCode = "405", description = "Validation exception"),
+                    @ApiResponse(description = "Unexpected error") 
+                })
     @Consumes({"application/json", "application/xml"})
-    public Pet updatePet(
+    public Response updatePet(
             @RequestBody(
                     description = "Pet object that needs to be updated in the store",
                     required = true,
@@ -194,9 +201,9 @@
         } catch (Exception e) {
             System.err.println("ERROR " + e.getMessage());
             e.printStackTrace();
-            throw new WebApplicationException("Internal error handling request", e);
+            throw new WebApplicationException("Unexpected error", e);
         }
-        return pet;
+        return Response.ok().entity(pet).build();
     }
 
 /*  @GET

src/main/java/io/swagger/petstore/utils/HandleAuthUrlProcessor.java

@@ -6,7 +6,7 @@
 public class HandleAuthUrlProcessor {
 
     public void process(OpenAPI openAPI) {
-        String oauthHost = StringUtils.isBlank(System.getenv("SWAGGER_OAUTH_HOST")) ? "https://petstore3.swagger.io" : System.getenv("SWAGGER_OAUTH_HOST");
+        String oauthHost = StringUtils.isBlank(System.getenv("SWAGGER_OAUTH_HOST")) ? "https://petstore31.swagger.io" : System.getenv("SWAGGER_OAUTH_HOST");
         if (StringUtils.isBlank(oauthHost)) {
             return;
         }

src/main/resources/openapi-configuration.json

@@ -10,13 +10,13 @@
         "info": {
             "version": "1.0",
             "title": "Swagger Pet Sample ",
-            "description": "This is a sample server 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/).  For this sample, you can use the api key `special-key` to test the authorization filters.",
-            "termsOfService": "http://swagger.io/terms/",
+            "description": "This is a sample server Petstore server.  You can find out more about Swagger at [https://swagger.io](https://swagger.io) or on [irc.freenode.net, #swagger](https://swagger.io/irc/).  For this sample, you can use the api key `special-key` to test the authorization filters.",
+            "termsOfService": "https://swagger.io/terms/",
             "contact": {
                 "email": "apiteam@swagger.io"
             },
             "license": {
-                "identifier": "license-id",
+                "identifier": "Apache-2.0",
                 "name": "Apache 2.0"
             }
         }