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 <[email protected]>
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>&invokeMethod</code> - The Java method name,
optionally with arguments if necessary to
* differentiate between methods.
* <li>
- * <code>&invokeArgs</code> - The arguments as a JSON array.
+ * <code>&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
[email protected].
