Merge pull request #603 from benjamin-confino/summary-in-info

Add summary attribute in info annotation
eclipse · May 9, 2024 · ce4b240 · ce4b240
2 parents dfedd16 + 82974af
commit ce4b240
Show file tree

Hide file tree

Showing 8 changed files with 42 additions and 4 deletions.
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/info/Info.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/info/Info.java
@@ -75,6 +75,13 @@
      **/
     String version();
 
+    /**
+     * The summary of the API.
+     *
+     * @return the summary for the API
+     **/
+    String summary() default "";
+
     /**
      * List of extensions to be added to the {@link org.eclipse.microprofile.openapi.models.info.Info Info} model
      * corresponding to the containing annotation.

diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/info/package-info.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/info/package-info.java
@@ -34,6 +34,6 @@
  * </pre>
  */
 
-@org.osgi.annotation.versioning.Version("1.1")
+@org.osgi.annotation.versioning.Version("1.2")
 @org.osgi.annotation.versioning.ProviderType
 package org.eclipse.microprofile.openapi.annotations.info;
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/info/Info.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/info/Info.java
@@ -200,4 +200,31 @@ default Info version(String version) {
         return this;
     }
 
+    /**
+     * Returns the summary of the exposed API from this Info instance.
+     *
+     * @return the summary of the exposed API
+     **/
+    String getSummary();
+
+    /**
+     * Sets this Info instance's summary information for the exposed API.
+     *
+     * @param summary
+     *            the summary of the exposed API
+     */
+    void setSummary(String summary);
+
+    /**
+     * Sets this Info instance's summary of the API to the given summary and returns this instance of Info.
+     *
+     * @param summary
+     *            the summary for the exposed API
+     * @return this Info instance
+     */
+    default Info summary(String summary) {
+        setSummary(summary);
+        return this;
+    }
+
 }
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/info/package-info.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/info/package-info.java
@@ -40,6 +40,6 @@
  * </pre>
  */
 
-@org.osgi.annotation.versioning.Version("1.0")
+@org.osgi.annotation.versioning.Version("1.1")
 @org.osgi.annotation.versioning.ProviderType
 package org.eclipse.microprofile.openapi.models.info;
diff --git a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/JAXRSApp.java b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/JAXRSApp.java
@@ -73,6 +73,7 @@
                    info = @Info(title = "AirlinesRatingApp API", version = "1.0",
                                 description = "APIs for booking and managing air flights",
                                 termsOfService = "http://airlinesratingapp.com/terms",
+                                summary = "An API for an Airline application",
                                 contact = @Contact(name = "AirlinesRatingApp API Support",
                                                    url = "http://exampleurl.com/contact",
                                                    email = "techsupport@airlinesratingapp.com",

diff --git a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/petstore/PetStoreApp.java b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/petstore/PetStoreApp.java
@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2017 Contributors to the Eclipse Foundation
+ * Copyright (c) 2017, 2024 Contributors to the Eclipse Foundation
  * <p>
  * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a
  * copy of the License at
@@ -38,7 +38,8 @@
                                                    url = "http://www.apache.org/licenses/LICENSE-2.0.html"),
                                 contact = @Contact(name = "PetStore API Support",
                                                    url = "https://github.com/eclipse/microprofile-open-api",
-                                                   email = "support@petstore.com")),
+                                                   email = "support@petstore.com"),
+                                summary = "An API for a pet store"),
                    externalDocs = @ExternalDocumentation(url = "http://swagger.io",
                                                          description = "Find out more about our store"),
                    tags = {

diff --git a/tck/src/main/java/org/eclipse/microprofile/openapi/tck/AirlinesAppTest.java b/tck/src/main/java/org/eclipse/microprofile/openapi/tck/AirlinesAppTest.java
@@ -69,6 +69,7 @@ public void testInfo(String type) {
         ValidatableResponse vr = callEndpoint(type);
         vr.body("info.title", equalTo("AirlinesRatingApp API"));
         vr.body("info.version", equalTo("1.0"));
+        vr.body("info.summary", equalTo("An API for an Airline application"));
         vr.body("info.termsOfService", equalTo("http://airlinesratingapp.com/terms"));
         vr.body("info.x-info", equalTo("test-info"));
     }

diff --git a/tck/src/main/java/org/eclipse/microprofile/openapi/tck/ModelReaderAppTest.java b/tck/src/main/java/org/eclipse/microprofile/openapi/tck/ModelReaderAppTest.java
@@ -63,6 +63,7 @@ public void testInfo(String type) {
         ValidatableResponse vr = callEndpoint(type);
         vr.body("info.title", equalTo("AirlinesRatingApp API"));
         vr.body("info.version", equalTo("1.0"));
+        vr.body("info.summary", equalTo("An API for an Airline application"));
         vr.body("info.termsOfService", equalTo("http://airlinesratingapp.com/terms"));
     }