This is an automated email from the ASF dual-hosted git repository.

jamesbognar pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/juneau.git


The following commit(s) were added to refs/heads/master by this push:
     new 616513c  Swagger UI enhancements.
616513c is described below

commit 616513cc80c86614f57787689c52bddb013e4f87
Author: JamesBognar <jamesbog...@apache.org>
AuthorDate: Wed Apr 11 18:51:52 2018 -0400

    Swagger UI enhancements.
---
 .../apache/juneau/dto/swagger/ui/SwaggerUI.java    |  4 +-
 .../juneau/examples/rest/DirectoryResource.java    | 27 +++++++++--
 .../examples/rest/SystemPropertiesResource.java    | 21 ++++----
 .../examples/rest/petstore/PetStoreResource.java   | 56 ++++++++++++----------
 .../apache/juneau/rest/BasicRestInfoProvider.java  |  3 +-
 .../juneau/rest/converters/Introspectable.java     | 10 +++-
 .../apache/juneau/rest/converters/Queryable.java   | 14 +++++-
 7 files changed, 90 insertions(+), 45 deletions(-)

diff --git 
a/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/ui/SwaggerUI.java
 
b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/ui/SwaggerUI.java
index 38d6ef0..3a026e1 100644
--- 
a/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/ui/SwaggerUI.java
+++ 
b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/ui/SwaggerUI.java
@@ -311,13 +311,13 @@ public class SwaggerUI extends PojoSwap<Swagger,Div> {
                        select.child(option("model","model"));
                        div.child(div(si.copy().resolveRefs(s.swagger, new 
ArrayDeque<String>(), s.resolveRefsMaxDepth))._class("model 
active").attr("data-name", "model"));
                }
-               
+
                if (examples != null) {
                        for (Map.Entry<String,?> e : examples.entrySet()) {
                                String name = e.getKey();
                                String value = e.getValue().toString();
                                select.child(option(name, name));
-                               div.child(div(value.replaceAll("\\n", 
"\n"))._class("example").attr("data-name", name));
+                               div.child(div(value.replaceAll("\\n", 
"\n"))._class("example" + (si == null ? " active" : "")).attr("data-name", 
name));
                        }
                }
                
diff --git 
a/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/DirectoryResource.java
 
b/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/DirectoryResource.java
index 7e676c3..86477aa 100644
--- 
a/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/DirectoryResource.java
+++ 
b/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/DirectoryResource.java
@@ -136,6 +136,8 @@ public class DirectoryResource extends BasicRestServlet {
        @RestMethod(
                name=DELETE, 
                path="/*", 
+               summary="Delete file",
+               description="Delete a file on the file system.",
                guards=AdminGuard.class
        )
        public Object doDelete(RestRequest req) throws MethodNotAllowed {
@@ -151,9 +153,14 @@ public class DirectoryResource extends BasicRestServlet {
                return "File deleted";
        }
 
-       /** PUT request handler */
-       @RestMethod(name=PUT, path="/*", guards=AdminGuard.class)
-       public Object doPut(RestRequest req) throws MethodNotAllowed, 
InternalServerError {
+       @RestMethod(
+               name=PUT, 
+               path="/*", 
+               summary="Upload file",
+               description="Uploads a file to the file system.",
+               guards=AdminGuard.class
+       )
+       public Object doPut(RestRequest req) throws MethodNotAllowed, 
InternalServerError, Forbidden {
 
                if (! allowPuts)
                        throw new MethodNotAllowed("PUT not enabled");
@@ -174,7 +181,12 @@ public class DirectoryResource extends BasicRestServlet {
 
        /** VIEW request handler (overloaded GET for viewing file contents) */
        @SuppressWarnings("resource")
-       @RestMethod(name="VIEW", path="/*")
+       @RestMethod(
+               name="VIEW", 
+               path="/*",
+               summary="View file",
+               description="Views the contents of a file as plain text."
+       )
        public void doView(RestRequest req, RestResponse res) throws 
MethodNotAllowed, NotFound {
 
                if (! allowViews)
@@ -194,7 +206,12 @@ public class DirectoryResource extends BasicRestServlet {
 
        /** DOWNLOAD request handler (overloaded GET for downloading file 
contents) */
        @SuppressWarnings("resource")
-       @RestMethod(name="DOWNLOAD")
+       @RestMethod(
+               name="DOWNLOAD",
+               path="/*",
+               summary="Download file",
+               description="Download the contents of a file as an octet 
stream."
+       )
        public void doDownload(RestRequest req, RestResponse res) throws 
MethodNotAllowed, NotFound {
 
                if (! allowViews)
diff --git 
a/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/SystemPropertiesResource.java
 
b/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/SystemPropertiesResource.java
index 0b5b07d..b61d9b1 100644
--- 
a/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/SystemPropertiesResource.java
+++ 
b/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/SystemPropertiesResource.java
@@ -23,6 +23,7 @@ import org.apache.juneau.encoders.*;
 import org.apache.juneau.rest.*;
 import org.apache.juneau.rest.annotation.*;
 import org.apache.juneau.rest.annotation.Body;
+import org.apache.juneau.rest.exception.*;
 import org.apache.juneau.rest.helper.*;
 import org.apache.juneau.rest.widget.*;
 
@@ -103,7 +104,7 @@ public class SystemPropertiesResource extends 
BasicRestServlet {
        @SuppressWarnings({"rawtypes", "unchecked"})
        public Map getSystemProperties(
                        @Query(name="sort", description="Sort results 
alphabetically", _default="false", example="true") boolean sort
-               ) {
+               ) throws NotAcceptable {
 
                if (sort)
                        return new TreeMap(System.getProperties());
@@ -122,7 +123,7 @@ public class SystemPropertiesResource extends 
BasicRestServlet {
        )
        public String getSystemProperty(
                        @Path(description="The system property name.", 
example="PATH") String propertyName
-               ) {
+               ) throws NotAcceptable {
                
                return System.getProperty(propertyName);
        }
@@ -136,7 +137,7 @@ public class SystemPropertiesResource extends 
BasicRestServlet {
        public RedirectServletRoot setSystemProperty(
                        @Path(description="The system property name") String 
propertyName, 
                        @Body(description="The new system property value") 
String value
-               ) throws UserNotAdminException {
+               ) throws UserNotAdminException, NotAcceptable, 
UnsupportedMediaType {
                
                System.setProperty(propertyName, value);
                return RedirectServletRoot.INSTANCE;
@@ -150,7 +151,7 @@ public class SystemPropertiesResource extends 
BasicRestServlet {
        )
        public RedirectServletRoot setSystemProperties(
                        @Body(description="The new system property values", 
example="{key1:'val1',key2:123}") java.util.Properties newProperties
-               ) throws UserNotAdminException {
+               ) throws UserNotAdminException, NotAcceptable, 
UnsupportedMediaType {
                
                System.setProperties(newProperties);
                return RedirectServletRoot.INSTANCE;
@@ -163,8 +164,8 @@ public class SystemPropertiesResource extends 
BasicRestServlet {
                guards=AdminGuard.class
        )
        public RedirectServletRoot deleteSystemProperty(
-                       @Path(description="The system property name") String 
propertyName
-               ) throws UserNotAdminException {
+                       @Path(description="The system property name", 
example="PATH") String propertyName
+               ) throws UserNotAdminException, NotAcceptable {
                
                System.clearProperty(propertyName);
                return RedirectServletRoot.INSTANCE;
@@ -183,7 +184,7 @@ public class SystemPropertiesResource extends 
BasicRestServlet {
                        }
                )
        )
-       public Form getFormPage() {
+       public Form getFormPage() throws NotAcceptable {
                return 
form().method(POST).action("servlet:/formPagePost").children(
                        table(
                                tr(
@@ -209,7 +210,7 @@ public class SystemPropertiesResource extends 
BasicRestServlet {
        public RedirectServletRoot formPagePost(
                        @FormData("name") String name, 
                        @FormData("value") String value
-               ) throws UserNotAdminException {
+               ) throws UserNotAdminException, NotAcceptable, 
UnsupportedMediaType {
                
                System.setProperty(name, value);
                return RedirectServletRoot.INSTANCE;
@@ -220,8 +221,8 @@ public class SystemPropertiesResource extends 
BasicRestServlet {
        // Beans
        
//--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
        
-       @ResponseInfo(code=403, description="User is not an administrator.")
-       public static class UserNotAdminException extends RuntimeException {
+       @ResponseInfo( description="User is not an administrator.")
+       public static class UserNotAdminException extends Forbidden {
                private static final long serialVersionUID = 1L;
 
                public UserNotAdminException() {
diff --git 
a/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/petstore/PetStoreResource.java
 
b/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/petstore/PetStoreResource.java
index 6e913f6..358538c 100644
--- 
a/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/petstore/PetStoreResource.java
+++ 
b/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/petstore/PetStoreResource.java
@@ -21,8 +21,10 @@ import org.apache.juneau.internal.*;
 import org.apache.juneau.microservice.*;
 import org.apache.juneau.rest.*;
 import org.apache.juneau.rest.annotation.*;
+import org.apache.juneau.rest.exception.*;
 import org.apache.juneau.rest.helper.*;
 import org.apache.juneau.rest.widget.*;
+import org.apache.juneau.rest.converters.*;
 
 /**
  * Sample resource that shows how to generate ATOM feeds.
@@ -79,10 +81,14 @@ public class PetStoreResource extends BasicRestServletJena {
                path="/pet",
                summary="All pets in the store",
                swagger={
-                       "tags:['pet']"
-               }
+                       "tags:['pet'],",
+                       "parameters:[",
+                                Queryable.SWAGGER_PARAMS,
+                       "]"
+               },
+               converters={Queryable.class}
        )
-       public Collection<Pet> getPets() {
+       public Collection<Pet> getPets() throws NotAcceptable {
                return db.getPets();
        }
        
@@ -98,7 +104,7 @@ public class PetStoreResource extends BasicRestServletJena {
        )
        public Pet getPet(
                        @Path(description="ID of pet to return", example="123") 
long petId
-               ) throws IdNotFound {
+               ) throws IdNotFound, NotAcceptable {
                
                return db.getPet(petId);
        }
@@ -114,7 +120,7 @@ public class PetStoreResource extends BasicRestServletJena {
        )
        public Ok addPet(
                        @Body(description="Pet object that needs to be added to 
the store") Pet pet
-               ) throws IdConflict {
+               ) throws IdConflict, NotAcceptable, UnsupportedMediaType {
                
                db.add(pet);
                return OK;
@@ -131,7 +137,7 @@ public class PetStoreResource extends BasicRestServletJena {
        )
        public Ok updatePet(
                        @Body(description="Pet object that needs to be added to 
the store") Pet pet
-               ) throws IdNotFound {
+               ) throws IdNotFound, NotAcceptable, UnsupportedMediaType {
                
                db.update(pet);
                return OK;
@@ -155,7 +161,7 @@ public class PetStoreResource extends BasicRestServletJena {
                                example="['AVAILABLE','PENDING']"
                        ) 
                        PetStatus[] status
-               ) {
+               ) throws NotAcceptable {
                
                return db.getPetsByStatus(status);
        }
@@ -179,7 +185,7 @@ public class PetStoreResource extends BasicRestServletJena {
                                example="['tag1','tag2']"
                        ) 
                        String[] tags
-               ) throws InvalidTag {
+               ) throws InvalidTag, NotAcceptable {
                
                return db.getPetsByTags(tags);
        }
@@ -197,7 +203,7 @@ public class PetStoreResource extends BasicRestServletJena {
                        @Path(description="ID of pet that needs to be updated", 
example="123") long petId, 
                        @FormData(name="name", description="Updated name of the 
pet", example="'Scruffy'") String name, 
                        @FormData(name="status", description="Updated status of 
the pet", example="'AVAILABLE'") PetStatus status
-               ) throws IdNotFound {
+               ) throws IdNotFound, NotAcceptable, UnsupportedMediaType {
                
                Pet pet = db.getPet(petId);
                pet.name(name);
@@ -218,7 +224,7 @@ public class PetStoreResource extends BasicRestServletJena {
        public Ok deletePet(
                        @Header(name="api_key", example="foobar") String 
apiKey, 
                        @Path(description="Pet id to delete", example="123") 
long petId
-               ) throws IdNotFound {
+               ) throws IdNotFound, NotAcceptable {
                
                db.removePet(petId);
                return OK;
@@ -237,7 +243,7 @@ public class PetStoreResource extends BasicRestServletJena {
                        @Path(description="ID of pet to update", example="123") 
long petId, 
                        @FormData(name="additionalMetadata", 
description="Additional data to pass to server", example="Foobar") String 
additionalMetadata, 
                        @FormData(name="file", description="file to upload", 
required="true", type="file") byte[] file
-               ) {
+               ) throws NotAcceptable, UnsupportedMediaType {
                
                return OK;
        }
@@ -253,8 +259,8 @@ public class PetStoreResource extends BasicRestServletJena {
                swagger={
                        "tags:['store']"
                }
-       )
-       public Collection<Order> getOrders() {
+       ) 
+       public Collection<Order> getOrders() throws NotAcceptable {
                return db.getOrders();
        }
 
@@ -269,7 +275,7 @@ public class PetStoreResource extends BasicRestServletJena {
        )
        public Order getOrder(
                        @Path(description="ID of order to fetch", maximum="10", 
minimum="1", example="5") long orderId
-               ) throws InvalidId, IdNotFound {
+               ) throws InvalidId, IdNotFound, NotAcceptable {
                
                if (orderId < 0 || orderId > 10)
                        throw new InvalidId();
@@ -286,7 +292,7 @@ public class PetStoreResource extends BasicRestServletJena {
        )
        public Order placeOrder(
                        @Body(description="Order placed for purchasing the 
pet", example="{petId:456,quantity:100}") Order order
-               ) throws IdConflict {
+               ) throws IdConflict, NotAcceptable, UnsupportedMediaType {
                
                return db.add(order);
        }
@@ -302,7 +308,7 @@ public class PetStoreResource extends BasicRestServletJena {
        )
        public Ok deletePurchaseOrder(
                        @Path(description="ID of the order that needs to be 
deleted", minimum="1", example="5") long orderId
-               ) throws InvalidId, IdNotFound {
+               ) throws InvalidId, IdNotFound, NotAcceptable {
                
                if (orderId < 0)
                        throw new InvalidId();
@@ -323,7 +329,7 @@ public class PetStoreResource extends BasicRestServletJena {
                        "security:[ { api_key:[] } ]"
                }
        )
-       public Map<PetStatus,Integer> getStoreInventory() {
+       public Map<PetStatus,Integer> getStoreInventory() throws NotAcceptable {
                return db.getInventory();
        }
 
@@ -339,7 +345,7 @@ public class PetStoreResource extends BasicRestServletJena {
                        "tags:['user']"
                }
        )
-       public Collection<User> getUsers() {
+       public Collection<User> getUsers() throws NotAcceptable {
                return db.getUsers();
        }
 
@@ -353,7 +359,7 @@ public class PetStoreResource extends BasicRestServletJena {
        )
        public User getUser(
                        @Path(description="The name that needs to be fetched. 
Use user1 for testing.") String username
-               ) throws InvalidUsername, IdNotFound {
+               ) throws InvalidUsername, IdNotFound, NotAcceptable {
                
                return db.getUser(username);
        }
@@ -369,7 +375,7 @@ public class PetStoreResource extends BasicRestServletJena {
        )
        public Ok createUser(
                        @Body(description="Created user object") User user
-               ) throws InvalidUsername, IdConflict {
+               ) throws InvalidUsername, IdConflict, NotAcceptable, 
UnsupportedMediaType {
                
                db.add(user);
                return OK;
@@ -385,7 +391,7 @@ public class PetStoreResource extends BasicRestServletJena {
        )
        public Ok createUsers(
                        @Body(description="List of user objects") User[] users
-               ) throws InvalidUsername, IdConflict {
+               ) throws InvalidUsername, IdConflict, NotAcceptable, 
UnsupportedMediaType {
                
                for (User user : users)
                        db.add(user);
@@ -404,7 +410,7 @@ public class PetStoreResource extends BasicRestServletJena {
        public Ok updateUser(
                        @Path(description="Name that need to be updated") 
String username, 
                        @Body(description="Updated user object") User user
-               ) throws InvalidUsername, IdNotFound {
+               ) throws InvalidUsername, IdNotFound, NotAcceptable, 
UnsupportedMediaType {
                
                User oldUser = db.getUser(username);
                user.id(oldUser.getId());
@@ -423,7 +429,7 @@ public class PetStoreResource extends BasicRestServletJena {
        )
        public Ok deleteUser(
                        @Path(description="The name that needs to be deleted") 
String username
-               ) throws InvalidUsername, IdNotFound {
+               ) throws InvalidUsername, IdNotFound, NotAcceptable {
                
                User oldUser = db.getUser(username);
                db.removeUser(oldUser.getId());
@@ -451,7 +457,7 @@ public class PetStoreResource extends BasicRestServletJena {
                        @Query(name="password", description="The password for 
login in clear text", required="true", example="abc123") String password, 
                        RestRequest req, 
                        RestResponse res
-               ) throws InvalidLogin {
+               ) throws InvalidLogin, NotAcceptable {
                
                if (! db.isValid(username, password))
                        throw new InvalidLogin();
@@ -471,7 +477,7 @@ public class PetStoreResource extends BasicRestServletJena {
                        "tags:[ 'user' ]"
                }
        )
-       public Ok logout(RestRequest req) {
+       public Ok logout(RestRequest req) throws NotAcceptable {
                req.getSession().removeAttribute("login-expires");
                return OK;
        }
diff --git 
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/BasicRestInfoProvider.java
 
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/BasicRestInfoProvider.java
index 34a05fa..c65e2fa 100644
--- 
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/BasicRestInfoProvider.java
+++ 
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/BasicRestInfoProvider.java
@@ -323,7 +323,8 @@ public class BasicRestInfoProvider implements 
RestInfoProvider {
                                if (! tagMap.containsKey(tag))
                                        tagMap.put(tag, new 
ObjectMap().append("name", tag));
                        
-                       op.put("tags", tags);
+                       if (! tags.isEmpty())
+                               op.put("tags", tags);
                        
                        s = mb.findFirstString(locale, mn + ".externalDocs");
                        if (s != null) {
diff --git 
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/converters/Introspectable.java
 
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/converters/Introspectable.java
index ad6c018..c501c25 100644
--- 
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/converters/Introspectable.java
+++ 
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/converters/Introspectable.java
@@ -38,7 +38,7 @@ import org.apache.juneau.utils.*;
  *             <code>&amp;invokeMethod</code> - The Java method name, 
optionally with arguments if necessary to
  *             differentiate between methods.
  *     <li>
- *             <code>&amp;invokeArgs</code> - The arguments as a JSON array.
+ *             <code>&amp;invokeArgs</code> - The arguments as an array.
  * </ul>
  * 
  * <h5 class='section'>See Also:</h5>
@@ -50,6 +50,14 @@ import org.apache.juneau.utils.*;
  */
 public final class Introspectable implements RestConverter {
 
+       /**
+        * Swagger parameters for this converter.
+        */
+       public static final String SWAGGER_PARAMS= ""
+               + "{in:'query',name:'invokeMethod',description:' The Java 
method name, optionally with arguments if necessary to differentiate between 
methods.',x-examples:{example:'toString'}},"
+               + "{in:'query',name:'invokeArgs',description:'The arguments as 
an array.',x-examples:{example:'foo,bar'}}"
+       ;
+
        @Override /* RestConverter */
        @SuppressWarnings({"unchecked", "rawtypes"})
        public Object convert(RestRequest req, Object o) throws 
InternalServerError {
diff --git 
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/converters/Queryable.java
 
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/converters/Queryable.java
index bda9197..34e2f6a 100644
--- 
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/converters/Queryable.java
+++ 
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/converters/Queryable.java
@@ -70,7 +70,19 @@ import org.apache.juneau.utils.*;
  * </ul>
  */
 public final class Queryable implements RestConverter {
-
+       
+       /**
+        * Swagger parameters for this converter.
+        */
+       public static final String SWAGGER_PARAMS= ""
+               + "{in:'query',name:'s',description:'Search.\nComma-delimited 
list of key/value pairs representing column names and search tokens.\n\\'*\\' 
and \\'?\\' can be used as 
meta-characters.',schema:{type:'string'},x-examples:{example:'?s=Bill*,birthDate>2000'}},"
+               + "{in:'query',name:'v',description:'View.\nComma-delimited 
list of column names to 
display.',schema:{type:'string'},x-examples:{example:'?v=name,birthDate'}},"
+               + "{in:'query',name:'o',description:'Order by.\nComma-delimited 
list of columns to sort by.\nColumn names can be suffixed with \\'+\\' or 
\\'-\\' to indicate ascending or descending order.\nThe default is ascending 
order.',schema:{type:'string'},x-examples:{example:'?o=name,birthDate-'}},"
+               + "{in:'query',name:'i',description:'Case-insensitive.\nBoolean 
flag for case-insensitive matching on the search 
parameters.',schema:{type:'boolean'},x-examples:{example:'?i=true'}},"
+               + "{in:'query',name:'p',description:'Position.\nOnly return 
rows starting at the specified index position (zero-indexed).\nDefault is 
0',schema:{type:'integer'},x-examples:{example:'?p=100'}},"
+               + "{in:'query',name:'l',description:'Limit.\nOnly return the 
specified number of rows.\nDefault is 0 (meaning return all 
rows).',schema:{type:'integer'},x-examples:{example:'?l=100'}}"
+       ;
+       
        @Override /* RestConverter */
        public Object convert(RestRequest req, Object o) {
                if (o == null)

-- 
To stop receiving notification emails like this one, please contact
jamesbog...@apache.org.

Reply via email to