From commits-return-5203-archive-asf-public=cust-asf.ponee.io@juneau.apache.org Thu Mar 8 03:36:39 2018 Return-Path: X-Original-To: archive-asf-public@cust-asf.ponee.io Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by mx-eu-01.ponee.io (Postfix) with SMTP id 35231180656 for ; Thu, 8 Mar 2018 03:36:36 +0100 (CET) Received: (qmail 62168 invoked by uid 500); 8 Mar 2018 02:36:35 -0000 Mailing-List: contact commits-help@juneau.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@juneau.apache.org Delivered-To: mailing list commits@juneau.apache.org Received: (qmail 62159 invoked by uid 99); 8 Mar 2018 02:36:35 -0000 Received: from ec2-52-202-80-70.compute-1.amazonaws.com (HELO gitbox.apache.org) (52.202.80.70) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 08 Mar 2018 02:36:35 +0000 Received: by gitbox.apache.org (ASF Mail Server at gitbox.apache.org, from userid 33) id 367D380648; Thu, 8 Mar 2018 02:36:34 +0000 (UTC) Date: Thu, 08 Mar 2018 02:36:34 +0000 To: "commits@juneau.apache.org" Subject: [juneau] branch master updated: Simplified swagger annotations. MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Message-ID: <152047659413.8945.3236698918731466245@gitbox.apache.org> From: jamesbognar@apache.org X-Git-Host: gitbox.apache.org X-Git-Repo: juneau X-Git-Refname: refs/heads/master X-Git-Reftype: branch X-Git-Oldrev: e3f62d056922a22e18f02c56868507918fce4ae2 X-Git-Newrev: bad860b6a5539360026734e83f4462c9cf3ee70f X-Git-Rev: bad860b6a5539360026734e83f4462c9cf3ee70f X-Git-NotificationType: ref_changed_plus_diff X-Git-Multimail-Version: 1.5.dev Auto-Submitted: auto-generated 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 bad860b Simplified swagger annotations. bad860b is described below commit bad860b6a5539360026734e83f4462c9cf3ee70f Author: JamesBognar AuthorDate: Wed Mar 7 21:36:25 2018 -0500 Simplified swagger annotations. --- .../apache/juneau/dto/swagger/OperationTest.java | 18 +- .../org/apache/juneau/dto/swagger/Operation.java | 12 +- juneau-doc/src/main/javadoc/overview.html | 238 ++-- .../examples/rest/SystemPropertiesResource.java | 118 +- .../rest/addressbook/AddressBookResource.java | 16 +- .../microservice/resources/ConfigResource.java | 68 +- .../microservice/resources/LogsResource.java | 45 +- .../org/apache/juneau/rest/test/NlsResource.java | 70 +- .../rest/test/OptionsWithoutNlsResource.java | 6 +- .../java/org/apache/juneau/rest/test/NlsTest.java | 12 +- .../apache/juneau/rest/BasicRestInfoProvider.java | 1410 ++++---------------- .../java/org/apache/juneau/rest/RestRequest.java | 4 +- .../juneau/rest/annotation/MethodSwagger.java | 210 --- .../apache/juneau/rest/annotation/Parameter.java | 213 --- .../juneau/rest/annotation/ResourceSwagger.java | 333 ----- .../apache/juneau/rest/annotation/Response.java | 107 -- .../apache/juneau/rest/annotation/RestMethod.java | 35 +- .../juneau/rest/annotation/RestResource.java | 22 +- 18 files changed, 615 insertions(+), 2322 deletions(-) diff --git a/juneau-core/juneau-core-test/src/test/java/org/apache/juneau/dto/swagger/OperationTest.java b/juneau-core/juneau-core-test/src/test/java/org/apache/juneau/dto/swagger/OperationTest.java index 1f44ad1..5549d6f 100644 --- a/juneau-core/juneau-core-test/src/test/java/org/apache/juneau/dto/swagger/OperationTest.java +++ b/juneau-core/juneau-core-test/src/test/java/org/apache/juneau/dto/swagger/OperationTest.java @@ -352,11 +352,11 @@ public class OperationTest { public void testSetResponses() { Operation t = new Operation(); - t.setResponses(new AMap().append(123,responseInfo("bar"))); + t.setResponses(new AMap().append("123",responseInfo("bar"))); assertObjectEquals("{'123':{description:'bar'}}", t.getResponses()); assertType(Map.class, t.getResponses()); - t.setResponses(new AMap()); + t.setResponses(new AMap()); assertObjectEquals("{}", t.getResponses()); assertType(Map.class, t.getResponses()); @@ -371,11 +371,11 @@ public class OperationTest { public void testAddResponses() { Operation t = new Operation(); - t.addResponses(new AMap().append(123,responseInfo("bar"))); + t.addResponses(new AMap().append("123",responseInfo("bar"))); assertObjectEquals("{'123':{description:'bar'}}", t.getResponses()); assertType(Map.class, t.getResponses()); - t.addResponses(new AMap()); + t.addResponses(new AMap()); assertObjectEquals("{'123':{description:'bar'}}", t.getResponses()); assertType(Map.class, t.getResponses()); @@ -391,9 +391,9 @@ public class OperationTest { public void testResponse() { Operation t = new Operation(); - t.response(1, responseInfo("foo")); + t.response("1", responseInfo("foo")); t.response(null, responseInfo("bar")); - t.response(2, null); + t.response("2", null); assertObjectEquals("{'1':{description:'foo'},null:{description:'bar'},'2':null}", t.getResponses()); } @@ -411,8 +411,8 @@ public class OperationTest { t.responses((Object)null); assertObjectEquals("{'1':{description:'a'},'2':{description:'b'},'3':{description:'c'}}", t.getResponses()); - for (Map.Entry e : t.getResponses().entrySet()) { - assertType(Integer.class, e.getKey()); + for (Map.Entry e : t.getResponses().entrySet()) { + assertType(String.class, e.getKey()); assertType(ResponseInfo.class, e.getValue()); } } @@ -656,7 +656,7 @@ public class OperationTest { assertType(List.class, t.get("produces", Object.class)); assertType(MediaType.class, t.get("produces", List.class).get(0)); assertType(Map.class, t.get("responses", Object.class)); - assertType(Integer.class, t.get("responses", Map.class).keySet().iterator().next()); + assertType(String.class, t.get("responses", Map.class).keySet().iterator().next()); assertType(ResponseInfo.class, t.get("responses", Map.class).values().iterator().next()); assertType(List.class, t.get("schemes", Object.class)); assertType(List.class, t.get("security", Object.class)); diff --git a/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/Operation.java b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/Operation.java index 77ffa4c..edfd442 100644 --- a/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/Operation.java +++ b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/Operation.java @@ -141,7 +141,7 @@ public class Operation extends SwaggerElement { produces; private List parameters; private List>> security; - private Map responses; + private Map responses; /** * Bean property getter: tags. @@ -697,7 +697,7 @@ public class Operation extends SwaggerElement { * * @return The property value, or null if it is not set. */ - public Map getResponses() { + public Map getResponses() { return responses; } @@ -712,7 +712,7 @@ public class Operation extends SwaggerElement { *
Property value is required. * @return This object (for method chaining). */ - public Operation setResponses(Map value) { + public Operation setResponses(Map value) { responses = newMap(value); return this; } @@ -728,7 +728,7 @@ public class Operation extends SwaggerElement { *
Ignored if null. * @return This object (for method chaining). */ - public Operation addResponses(Map values) { + public Operation addResponses(Map values) { responses = addToMap(responses, values); return this; } @@ -740,7 +740,7 @@ public class Operation extends SwaggerElement { * @param response The response description. * @return This object (for method chaining). */ - public Operation response(Integer statusCode, ResponseInfo response) { + public Operation response(String statusCode, ResponseInfo response) { return addResponses(Collections.singletonMap(statusCode, response)); } @@ -761,7 +761,7 @@ public class Operation extends SwaggerElement { * @return This object (for method chaining). */ public Operation responses(Object...value) { - responses = addToMap(responses, value, Integer.class, ResponseInfo.class); + responses = addToMap(responses, value, String.class, ResponseInfo.class); return this; } diff --git a/juneau-doc/src/main/javadoc/overview.html b/juneau-doc/src/main/javadoc/overview.html index d9005a7..dc56b02 100644 --- a/juneau-doc/src/main/javadoc/overview.html +++ b/juneau-doc/src/main/javadoc/overview.html @@ -13723,31 +13723,6 @@ certain aspects.

- In addition to the methods defined on the RestInfoProvider interface, it also includes the following methods: -

-
    -
  • {@link org.apache.juneau.rest.BasicRestInfoProvider} implements {@link org.apache.juneau.rest.RestInfoProvider} -
      -
    • {@link org.apache.juneau.rest.BasicRestInfoProvider#getVersion(RestRequest) getVersion(RestRequest)} -
    • {@link org.apache.juneau.rest.BasicRestInfoProvider#getContact(RestRequest) getContact(RestRequest)} -
    • {@link org.apache.juneau.rest.BasicRestInfoProvider#getConsumes(RestRequest) getConsumes(RestRequest)} -
    • {@link org.apache.juneau.rest.BasicRestInfoProvider#getProduces(RestRequest) getProduces(RestRequest)} -
    • {@link org.apache.juneau.rest.BasicRestInfoProvider#getLicense(RestRequest) getLicense(RestRequest)} -
    • {@link org.apache.juneau.rest.BasicRestInfoProvider#getTags(RestRequest) getTags(RestRequest)} -
    • {@link org.apache.juneau.rest.BasicRestInfoProvider#getTermsOfService(RestRequest) getTermsOfService(RestRequest)} -
    • {@link org.apache.juneau.rest.BasicRestInfoProvider#getExternalDocs(RestRequest) getExternalDocs(RestRequest)} -
    • {@link org.apache.juneau.rest.BasicRestInfoProvider#getMethodSummary(Method,RestRequest) getMethodSummary(Method,RestRequest)} -
    • {@link org.apache.juneau.rest.BasicRestInfoProvider#getMethodDescription(Method,RestRequest) getMethodDescription(Method,RestRequest)} -
    • {@link org.apache.juneau.rest.BasicRestInfoProvider#getMethodOperationId(Method,RestRequest) getMethodOperationId(Method,RestRequest)} -
    • {@link org.apache.juneau.rest.BasicRestInfoProvider#getMethodConsumes(Method,RestRequest) getMethodConsumes(Method,RestRequest)} -
    • {@link org.apache.juneau.rest.BasicRestInfoProvider#getMethodProduces(Method,RestRequest) getMethodProduces(Method,RestRequest)} -
    • {@link org.apache.juneau.rest.BasicRestInfoProvider#getMethodParameters(Method,RestRequest) getMethodParameters(Method,RestRequest)} -
    • {@link org.apache.juneau.rest.BasicRestInfoProvider#getMethodResponses(Method,RestRequest) getMethodResponses(Method,RestRequest)} -
    • {@link org.apache.juneau.rest.BasicRestInfoProvider#getMethodTags(Method,RestRequest) getMethodTags(Method,RestRequest)} -
    • {@link org.apache.juneau.rest.BasicRestInfoProvider#getSwaggerFromFile(RestRequest) getSwaggerFromFile(RestRequest)} -
    -
-

The default provider provides several options for defining Swagger documentation on your resource:

    @@ -13761,12 +13736,12 @@ MyResource_ja_JP.json

  • - Use {@link org.apache.juneau.rest.annotation.ResourceSwagger @ResourceSwagger} and {@link org.apache.juneau.rest.annotation.MethodSwagger @MethodSwagger} + Use {@link org.apache.juneau.rest.annotation.RestResource#swagger() @RestResource(swagger)} and {@link org.apache.juneau.rest.annotation.RestMethod#swagger() @RestMethod(swagger)} annotations on your resource classes and methods.
    Example:

    @RestMethod( - swagger=@MethodSwagger(tags="foo,bar,baz") + swagger="{tags:'foo,bar,baz'} ) public Object myMethod() {...}

    @@ -17680,14 +17655,14 @@ // Support GZIP encoding on Accept-Encoding header. encoders=GzipEncoder.class, - swagger=@ResourceSwagger( - contact="{name:'John Smith',email:'john@smith.com'}", - license="{name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'}", - version="2.0", - termsOfService="You're on your own.", - tags="[{name:'Java',description:'Java utility',externalDocs:{description:'Home page',url:'http://juneau.apache.org'}}]", - externalDocs="{description:'Home page',url:'http://juneau.apache.org'}" - ) + swagger={ + "contact:{name:'John Smith',email:'john@smith.com'},", + "license:{name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'},", + "version:'2.0',", + "termsOfService:'You are on your own.',", + "tags:[{name:'Java',description:'Java utility'}],", + "externalDocs:{description:'Home page',url:'http://juneau.apache.org'}" + } ) public class SystemPropertiesResource extends BasicRestServlet { @@ -17695,14 +17670,14 @@ name=GET, path="/", summary="Show all system properties", description="Returns all system properties defined in the JVM.", - swagger=@MethodSwagger( - parameters={ - @Parameter(in="query", name="sort", description="Sort results alphabetically.", _default="false") - }, - responses={ - @Response(value=200, description="Returns a map of key/value pairs.") - } - ) + swagger={ + "parameters:[", + "{name:'sort',in:'query',description:'Sort results alphabetically',default:'false'}", + "],", + "responses:{", + "200: {description:'Returns a map of key/value pairs.'}", + "}" + } ) public Map getSystemProperties(@Query("sort") boolean sort) throws Throwable { if (sort) @@ -17714,14 +17689,14 @@ name=GET, path="/{propertyName}", summary="Get system property", description="Returns the value of the specified system property.", - swagger=@MethodSwagger( - parameters={ - @Parameter(in="path", name="propertyName", description="The system property name.") - }, - responses={ - @Response(value=200, description="The system property value, or null if not found.") - } - ) + swagger={ + "parameters:[", + "{name:'propertyName',in:'path',description:'The system property name.'}", + "],", + "responses:{", + "200: {description:'The system property value, or null if not found.'}", + "}" + } ) public String getSystemProperty(@Path String propertyName) throws Throwable { return System.getProperty(propertyName); @@ -17732,20 +17707,16 @@ summary="Replace system property", description="Sets a new value for the specified system property.", guards=AdminGuard.class, - swagger=@MethodSwagger( - parameters={ - @Parameter(in="path", name="propertyName", description="The system property name."), - @Parameter(in="body", description="The new system property value."), - }, - responses={ - @Response(value=302, - headers={ - @Parameter(name="Location", description="The root URL of this resource.") - } - ), - @Response(value=403, description="User is not an admin.") - } - ) + swagger={ + "parameters:[", + "{name:'propertyName',in:'path',description:'The system property name.'},", + "{in:'body',description:'The new system property value.'}", + "],", + "responses:{", + "302: {headers:{Location:{description:'The root URL of this resource.'}}},", + "403: {description:'User is not an admin.'}", + "}" + } ) public Redirect setSystemProperty(@Path String propertyName, @Body String value) { System.setProperty(propertyName, value); @@ -17757,20 +17728,16 @@ summary="Add an entire set of system properties", description="Takes in a map of key/value pairs and creates a set of new system properties.", guards=AdminGuard.class, - swagger=@MethodSwagger( - parameters={ - @Parameter(in="path", name="propertyName", description="The system property key."), - @Parameter(in="body", description="The new system property values.", schema="{example:{key1:'val1',key2:123}}"), - }, - responses={ - @Response(value=302, - headers={ - @Parameter(name="Location", description="The root URL of this resource.") - } - ), - @Response(value=403, description="Unauthorized: User is not an admin.") - } - ) + swagger={ + "parameters:[", + "{name:'propertyName',in:'path',description:'The system property name.'},", + "{in:'body',description:'The new system property values.',schema:{example:{key1:'val1',key2:123}}}", + "],", + "responses:{", + "302: {headers:{Location:{description:'The root URL of this resource.'}}},", + "403: {description:'User is not an admin.'}", + "}" + } ) public Redirect setSystemProperties(@Body java.util.Properties newProperties) { System.setProperties(newProperties); @@ -17782,19 +17749,15 @@ summary="Delete system property", description="Deletes the specified system property.", guards=AdminGuard.class, - swagger=@MethodSwagger( - parameters={ - @Parameter(in="path", name="propertyName", description="The system property name."), - }, - responses={ - @Response(value=302, - headers={ - @Parameter(name="Location", description="The root URL of this resource.") - } - ), - @Response(value=403, description="Unauthorized: User is not an admin") - } - ) + swagger={ + "parameters:[", + "{name:'propertyName',in:'path',description:'The system property name.'}", + "],", + "responses:{", + "302: {headers:{Location:{description:'The root URL of this resource.'}}},", + "403: {description:'User is not an admin.'}", + "}" + } ) public Redirect deleteSystemProperty(@Path String propertyName) { System.clearProperty(propertyName); @@ -18944,14 +18907,14 @@ encoders=GzipEncoder.class, // Swagger info. - swagger=@ResourceSwagger( - contact="{name:'John Smith',email:'john@smith.com'}", - license="{name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'}", - version="2.0", - termsOfService="You're on your own.", - tags="[{name:'Java',description:'Java utility',externalDocs:{description:'Home page',url:'http://juneau.apache.org'}}]", - externalDocs="{description:'Home page',url:'http://juneau.apache.org'}" - ) + swagger= { + "contact:{name:'John Smith',email:'john@smith.com'},", + "license:{name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'},", + "version:'2.0',", + "termsOfService:'You're on your own.',", + "tags:[{name:'Java',description:'Java utility',externalDocs:{description:'Home page',url:'http://juneau.apache.org'}}],", + "externalDocs:{description:'Home page',url:'http://juneau.apache.org'}" + } ) public class AddressBookResource extends BasicRestServletJena { @@ -20700,11 +20663,11 @@ @RestMethod(name=GET, path="/{section}", description="Show config file section.", - swagger=@MethodSwagger( - parameters={ - @Parameter(in="path", name="section", description="Section name.") - } - ) + swagger={ + "parameters:[", + "{name:'section',in:'path',description:'Section name.'}", + "]" + } ) public ObjectMap getConfigSection(@Path("section") String section) throws Exception { return getSection(section); @@ -20712,12 +20675,12 @@ @RestMethod(name=GET, path="/{section}/{key}", description="Show config file entry.", - swagger=@MethodSwagger( - parameters={ - @Parameter(in="path", name="section", description="Section name."), - @Parameter(in="path", name="key", description="Entry name.") - } - ) + swagger={ + "parameters:[", + "{name:'section',in:'path',description:'Section name.'},", + "{name:'key',in:'path',description:'Entry name.'}", + "]" + } ) public String getConfigEntry(@Path("section") String section, @Path("key") String key) throws Exception { return getSection(section).getString(key); @@ -20725,11 +20688,11 @@ @RestMethod(name=POST, path="/", description="Sets contents of config file from a FORM post.", - swagger=@MethodSwagger( - parameters={ - @Parameter(in="formData", name="contents", description="New contents in INI file format.") - } - ) + swagger={ + "parameters:[", + "{name:'contents',in:'formData',description:'New contents in INI file format.'}", + "]" + } ) public Config setConfigContentsFormPost(@FormData("contents") String contents) throws Exception { return setConfigContents(new StringReader(contents)); @@ -20737,11 +20700,11 @@ @RestMethod(name=PUT, path="/", description="Sets contents of config file.", - swagger=@MethodSwagger( - parameters={ - @Parameter(in="body", description="New contents in INI file format.") - } - ) + swagger={ + "parameters:[", + "{in:'body',description:'New contents in INI file format.'}", + "]" + } ) public Config setConfigContents(@Body Reader contents) throws Exception { return getServletConfig().getConfig().load(contents, true).asMap(); @@ -20749,12 +20712,12 @@ @RestMethod(name=PUT, path="/{section}", description="Add or overwrite a config file section.", - swagger=@MethodSwagger( - parameters={ - @Parameter(in="path", name="section", description="Section name."), - @Parameter(in="body", description="New contents for section as a simple map with string keys and values.") - } - ) + swagger={ + "parameters:[", + "{name:'section',in:'path',description:'Section name.'}", + "{in:'body',description:'New contents for section as a simple map with string keys and values.'}", + "]" + } ) public ObjectMap setConfigSection(@Path("section") String section, @Body Map<String,String> contents) throws Exception { getServletConfig().getConfig().setSection(section, contents); @@ -20763,13 +20726,13 @@ @RestMethod(name=PUT, path="/{section}/{key}", description="Add or overwrite a config file entry.", - swagger=@MethodSwagger( - parameters={ - @Parameter(in="path", name="section", description="Section name."), - @Parameter(in="path", name="key", description="Entry name."), - @Parameter(in="body", description="New value as a string.") - } - ) + swagger={ + "parameters:[", + "{name:'section',in:'path',description:'Section name.'}", + "{name:'key',in:'path',description:'Entry name.'}", + "{in:'body',description:'New value as a string.'}", + "]" + } ) public String setConfigSection(@Path("section") String section, @Path("key") String key, @Body String value) throws Exception { getServletConfig().getConfig().put(section, key, value, false); @@ -20814,11 +20777,11 @@
  • Summary and detail views of the same beans providing different levels of information.
  • - The use of the {@link org.apache.juneau.html.annotation.HtmlRender @HtmlRender} annotation. + The use of the {@link org.apache.juneau.html.HtmlRender} class.
  • The use of the {@link org.apache.juneau.annotation.BeanProperty#format @BeanProperty(format)} annotation.
  • - The use of the {@link org.apache.juneau.rest.converters.Querable} interface. + The use of the {@link org.apache.juneau.rest.converters.Queryable} interface.
PetStoreResource.java
@@ -21300,6 +21263,9 @@
juneau-server
  • + Simplified {@link org.apache.juneau.rest.annotation.RestResource#swagger() @RestResource(swagger)} + and {@link org.apache.juneau.rest.annotation.RestMethod#swagger() @RestMethod(swagger)} annotations. +
  • Fixed bug in UriResolver when request path info had special characters.
  • Fixed bug where incorrect media type was being set on responses (e.g. text/html+schema instead of text/html for schema documents). 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 5c56c7d..fafba3d 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 @@ -78,14 +78,14 @@ import org.apache.juneau.rest.widget.*; // Support GZIP encoding on Accept-Encoding header. encoders=GzipEncoder.class, - swagger=@ResourceSwagger( - contact="{name:'John Smith',email:'john@smith.com'}", - license="{name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'}", - version="2.0", - termsOfService="You're on your own.", - tags="[{name:'Java',description:'Java utility',externalDocs:{description:'Home page',url:'http://juneau.apache.org'}}]", - externalDocs="{description:'Home page',url:'http://juneau.apache.org'}" - ) + swagger={ + "contact:{name:'John Smith',email:'john@smith.com'},", + "license:{name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'},", + "version:'2.0',", + "termsOfService:'You are on your own.',", + "tags:[{name:'Java',description:'Java utility'}],", + "externalDocs:{description:'Home page',url:'http://juneau.apache.org'}" + } ) public class SystemPropertiesResource extends BasicRestServlet { private static final long serialVersionUID = 1L; @@ -94,14 +94,14 @@ public class SystemPropertiesResource extends BasicRestServlet { name=GET, path="/", summary="Show all system properties", description="Returns all system properties defined in the JVM.", - swagger=@MethodSwagger( - parameters={ - @Parameter(in="query", name="sort", description="Sort results alphabetically.", _default="false") - }, - responses={ - @Response(value=200, description="Returns a map of key/value pairs.") - } - ) + swagger={ + "parameters:[", + "{name:'sort',in:'query',description:'Sort results alphabetically',default:'false'}", + "],", + "responses:{", + "200: {description:'Returns a map of key/value pairs.'}", + "}" + } ) @SuppressWarnings({"rawtypes", "unchecked"}) public Map getSystemProperties(@Query("sort") boolean sort) throws Throwable { @@ -114,14 +114,14 @@ public class SystemPropertiesResource extends BasicRestServlet { name=GET, path="/{propertyName}", summary="Get system property", description="Returns the value of the specified system property.", - swagger=@MethodSwagger( - parameters={ - @Parameter(in="path", name="propertyName", description="The system property name.") - }, - responses={ - @Response(value=200, description="The system property value, or null if not found.") - } - ) + swagger={ + "parameters:[", + "{name:'propertyName',in:'path',description:'The system property name.'}", + "],", + "responses:{", + "200: {description:'The system property value, or null if not found.'}", + "}" + } ) public String getSystemProperty(@Path String propertyName) throws Throwable { return System.getProperty(propertyName); @@ -132,20 +132,16 @@ public class SystemPropertiesResource extends BasicRestServlet { summary="Replace system property", description="Sets a new value for the specified system property.", guards=AdminGuard.class, - swagger=@MethodSwagger( - parameters={ - @Parameter(in="path", name="propertyName", description="The system property name."), - @Parameter(in="body", description="The new system property value."), - }, - responses={ - @Response(value=302, - headers={ - @Parameter(name="Location", description="The root URL of this resource.") - } - ), - @Response(value=403, description="User is not an admin.") - } - ) + swagger={ + "parameters:[", + "{name:'propertyName',in:'path',description:'The system property name.'},", + "{in:'body',description:'The new system property value.'}", + "],", + "responses:{", + "302: {headers:{Location:{description:'The root URL of this resource.'}}},", + "403: {description:'User is not an admin.'}", + "}" + } ) public Redirect setSystemProperty(@Path String propertyName, @Body String value) { System.setProperty(propertyName, value); @@ -157,20 +153,16 @@ public class SystemPropertiesResource extends BasicRestServlet { summary="Add an entire set of system properties", description="Takes in a map of key/value pairs and creates a set of new system properties.", guards=AdminGuard.class, - swagger=@MethodSwagger( - parameters={ - @Parameter(in="path", name="propertyName", description="The system property key."), - @Parameter(in="body", description="The new system property values.", schema="{example:{key1:'val1',key2:123}}"), - }, - responses={ - @Response(value=302, - headers={ - @Parameter(name="Location", description="The root URL of this resource.") - } - ), - @Response(value=403, description="Unauthorized: User is not an admin.") - } - ) + swagger={ + "parameters:[", + "{name:'propertyName',in:'path',description:'The system property name.'},", + "{in:'body',description:'The new system property values.',schema:{example:{key1:'val1',key2:123}}}", + "],", + "responses:{", + "302: {headers:{Location:{description:'The root URL of this resource.'}}},", + "403: {description:'User is not an admin.'}", + "}" + } ) public Redirect setSystemProperties(@Body java.util.Properties newProperties) { System.setProperties(newProperties); @@ -182,19 +174,15 @@ public class SystemPropertiesResource extends BasicRestServlet { summary="Delete system property", description="Deletes the specified system property.", guards=AdminGuard.class, - swagger=@MethodSwagger( - parameters={ - @Parameter(in="path", name="propertyName", description="The system property name."), - }, - responses={ - @Response(value=302, - headers={ - @Parameter(name="Location", description="The root URL of this resource.") - } - ), - @Response(value=403, description="Unauthorized: User is not an admin") - } - ) + swagger={ + "parameters:[", + "{name:'propertyName',in:'path',description:'The system property name.'}", + "],", + "responses:{", + "302: {headers:{Location:{description:'The root URL of this resource.'}}},", + "403: {description:'User is not an admin.'}", + "}" + } ) public Redirect deleteSystemProperty(@Path String propertyName) { System.clearProperty(propertyName); diff --git a/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/addressbook/AddressBookResource.java b/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/addressbook/AddressBookResource.java index 20713ca..cffd736 100644 --- a/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/addressbook/AddressBookResource.java +++ b/juneau-examples/juneau-examples-rest/src/main/java/org/apache/juneau/examples/rest/addressbook/AddressBookResource.java @@ -114,14 +114,14 @@ import org.apache.juneau.utils.*; encoders=GzipEncoder.class, // Swagger info. - swagger=@ResourceSwagger( - contact="{name:'John Smith',email:'john@smith.com'}", - license="{name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'}", - version="2.0", - termsOfService="You're on your own.", - tags="[{name:'Java',description:'Java utility',externalDocs:{description:'Home page',url:'http://juneau.apache.org'}}]", - externalDocs="{description:'Home page',url:'http://juneau.apache.org'}" - ) + swagger= { + "contact:{name:'John Smith',email:'john@smith.com'},", + "license:{name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'},", + "version:'2.0',", + "termsOfService:'You're on your own.',", + "tags:[{name:'Java',description:'Java utility',externalDocs:{description:'Home page',url:'http://juneau.apache.org'}}],", + "externalDocs:{description:'Home page',url:'http://juneau.apache.org'}" + } ) public class AddressBookResource extends BasicRestServletJena { private static final long serialVersionUID = 1L; diff --git a/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/ConfigResource.java b/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/ConfigResource.java index d42919d..4d27d6d 100755 --- a/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/ConfigResource.java +++ b/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/ConfigResource.java @@ -86,11 +86,11 @@ public class ConfigResource extends BasicRestServlet { */ @RestMethod(name=GET, path="/{section}", description="Show config file section.", - swagger=@MethodSwagger( - parameters={ - @Parameter(in="path", name="section", description="Section name.") - } - ) + swagger={ + "parameters:[", + "{name:'section',in:'path',description:'Section name.'}", + "]" + } ) public ObjectMap getConfigSection(@Path("section") String section) throws Exception { return getSection(section); @@ -106,12 +106,12 @@ public class ConfigResource extends BasicRestServlet { */ @RestMethod(name=GET, path="/{section}/{key}", description="Show config file entry.", - swagger=@MethodSwagger( - parameters={ - @Parameter(in="path", name="section", description="Section name."), - @Parameter(in="path", name="key", description="Entry name.") - } - ) + swagger={ + "parameters:[", + "{name:'section',in:'path',description:'Section name.'},", + "{name:'key',in:'path',description:'Entry name.'}", + "]" + } ) public String getConfigEntry(@Path("section") String section, @Path("key") String key) throws Exception { return getSection(section).getString(key); @@ -126,11 +126,11 @@ public class ConfigResource extends BasicRestServlet { */ @RestMethod(name=POST, path="/", description="Sets contents of config file from a FORM post.", - swagger=@MethodSwagger( - parameters={ - @Parameter(in="formData", name="contents", description="New contents in INI file format.") - } - ) + swagger={ + "parameters:[", + "{name:'contents',in:'formData',description:'New contents in INI file format.'}", + "]" + } ) public ObjectMap setConfigContentsFormPost(@FormData("contents") String contents) throws Exception { return setConfigContents(new StringReader(contents)); @@ -145,11 +145,11 @@ public class ConfigResource extends BasicRestServlet { */ @RestMethod(name=PUT, path="/", description="Sets contents of config file.", - swagger=@MethodSwagger( - parameters={ - @Parameter(in="body", description="New contents in INI file format.") - } - ) + swagger={ + "parameters:[", + "{in:'body',description:'New contents in INI file format.'}", + "]" + } ) public ObjectMap setConfigContents(@Body Reader contents) throws Exception { return getServletConfig().getConfig().load(contents, true).asMap(); @@ -165,12 +165,12 @@ public class ConfigResource extends BasicRestServlet { */ @RestMethod(name=PUT, path="/{section}", description="Add or overwrite a config file section.", - swagger=@MethodSwagger( - parameters={ - @Parameter(in="path", name="section", description="Section name."), - @Parameter(in="body", description="New contents for section as a simple map with string keys and values.") - } - ) + swagger={ + "parameters:[", + "{name:'section',in:'path',description:'Section name.'}", + "{in:'body',description:'New contents for section as a simple map with string keys and values.'}", + "]" + } ) public ObjectMap setConfigSection(@Path("section") String section, @Body Map contents) throws Exception { getServletConfig().getConfig().setSection(section, null, contents); @@ -188,13 +188,13 @@ public class ConfigResource extends BasicRestServlet { */ @RestMethod(name=PUT, path="/{section}/{key}", description="Add or overwrite a config file entry.", - swagger=@MethodSwagger( - parameters={ - @Parameter(in="path", name="section", description="Section name."), - @Parameter(in="path", name="key", description="Entry name."), - @Parameter(in="body", description="New value as a string.") - } - ) + swagger={ + "parameters:[", + "{name:'section',in:'path',description:'Section name.'}", + "{name:'key',in:'path',description:'Entry name.'}", + "{in:'body',description:'New value as a string.'}", + "]" + } ) public String setConfigSection(@Path("section") String section, @Path("key") String key, @Body String value) throws Exception { getServletConfig().getConfig().set(section + '/' + key, value); diff --git a/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/LogsResource.java b/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/LogsResource.java index a90ab98..6ba43d1 100755 --- a/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/LogsResource.java +++ b/juneau-microservice/juneau-microservice-server/src/main/java/org/apache/juneau/microservice/resources/LogsResource.java @@ -91,9 +91,12 @@ public class LogsResource extends BasicRestServlet { @RestMethod( name=GET, path="/*", - swagger=@MethodSwagger( - responses={@Response(200),@Response(404)} - ) + swagger= { + "responses:{", + "200: {description:'OK'},", + "404: {description:'Not Found'}", + "}" + } ) public Object getFileOrDirectory(RestRequest req, RestResponse res, RequestProperties properties, @PathRemainder String path) throws Exception { @@ -132,9 +135,12 @@ public class LogsResource extends BasicRestServlet { @RestMethod( name="VIEW", path="/*", - swagger=@MethodSwagger( - responses={@Response(200),@Response(404)} - ) + swagger= { + "responses:{", + "200: {description:'OK'},", + "404: {description:'Not Found'}", + "}" + } ) public void viewFile(RestRequest req, RestResponse res, @PathRemainder String path, RequestProperties properties, @Query("highlight") boolean highlight, @Query("start") String start, @Query("end") String end, @Query("thread") String thread, @Query("loggers") String[] loggers, @Query("severity") String[] severity) throws Exception { @@ -200,9 +206,12 @@ public class LogsResource extends BasicRestServlet { name="PARSE", path="/*", converters=Queryable.class, - swagger=@MethodSwagger( - responses={@Response(200),@Response(404)} - ) + swagger= { + "responses:{", + "200: {description:'OK'},", + "404: {description:'Not Found'}", + "}" + } ) public LogParser viewParsedEntries(RestRequest req, @PathRemainder String path, @Query("start") String start, @Query("end") String end, @Query("thread") String thread, @Query("loggers") String[] loggers, @Query("severity") String[] severity) throws Exception { @@ -226,9 +235,12 @@ public class LogsResource extends BasicRestServlet { @RestMethod( name="DOWNLOAD", path="/*", - swagger=@MethodSwagger( - responses={@Response(200),@Response(404)} - ) + swagger= { + "responses:{", + "200: {description:'OK'},", + "404: {description:'Not Found'}", + "}" + } ) public Object downloadFile(RestResponse res, @PathRemainder String path) throws Exception { @@ -252,9 +264,12 @@ public class LogsResource extends BasicRestServlet { @RestMethod( name=DELETE, path="/*", - swagger=@MethodSwagger( - responses={@Response(200),@Response(404)} - ) + swagger= { + "responses:{", + "200: {description:'OK'},", + "404: {description:'Not Found'}", + "}" + } ) public Object deleteFile(@PathRemainder String path) throws Exception { diff --git a/juneau-microservice/juneau-microservice-test/src/main/java/org/apache/juneau/rest/test/NlsResource.java b/juneau-microservice/juneau-microservice-test/src/main/java/org/apache/juneau/rest/test/NlsResource.java index 46fbab8..279e702 100644 --- a/juneau-microservice/juneau-microservice-test/src/main/java/org/apache/juneau/rest/test/NlsResource.java +++ b/juneau-microservice/juneau-microservice-test/src/main/java/org/apache/juneau/rest/test/NlsResource.java @@ -50,26 +50,21 @@ public class NlsResource extends BasicRestServletGroup { @RestMethod( name=POST, path="/{a}", description="Test1.c", - swagger=@MethodSwagger( - parameters={ - @Parameter(in="path", name="a", description="Test1.d"), - @Parameter(in="query", name="b", description="Test1.e"), - @Parameter(in="body", description="Test1.f"), - @Parameter(in="header", name="D", description="Test1.g"), - @Parameter(in="path", name="a2", description="Test1.h"), - @Parameter(in="query", name="b2", description="Test1.i"), - @Parameter(in="header", name="D2", description="Test1.j"), - }, - responses={ - @Response(200), - @Response(value=201, - description="Test1.l", - headers={ - @Parameter(in="foo", name="bar", description="Test1.m"), - } - ) - } - ) + swagger= { + "parameters:[", + "{name:'a',in:'path',type:'string',description:'Test1.d'},", + "{name:'b',in:'query',type:'string',description:'Test1.e'},", + "{in:'body',type:'string',description:'Test1.f'},", + "{name:'D',in:'header',type:'string',description:'Test1.g'},", + "{name:'a2',in:'path',type:'string',description:'Test1.h'},", + "{name:'b2',in:'query',type:'string',description:'Test1.i'},", + "{name:'D2',in:'header',type:'string',description:'Test1.j'}", + "],", + "responses:{", + "200: {description:'OK'},", + "201: {description:'Test1.l',headers:{bar:{description:'Test1.m',type:'string'}}}", + "}" + } ) public String test1(@Path("a") String a, @Query("b") String b, @Body String c, @Header("D") String d, @Path("e") String e, @Query("f") String f, @Header("g") String g) { @@ -170,26 +165,21 @@ public class NlsResource extends BasicRestServletGroup { @RestMethod( name=POST, path="/{a}", description="$L{foo}", - swagger=@MethodSwagger( - parameters={ - @Parameter(in="path", name="a", description="$L{foo}"), - @Parameter(in="query", name="b", description="$L{foo}"), - @Parameter(in="body", description="$L{foo}"), - @Parameter(in="header", name="D", description="$L{foo}"), - @Parameter(in="path", name="a2", description="$L{foo}"), - @Parameter(in="query", name="b2", description="$L{foo}"), - @Parameter(in="header", name="D2", description="$L{foo}") - }, - responses={ - @Response(200), - @Response(value=201, - description="$L{foo}", - headers={ - @Parameter(in="foo", name="bar", description="$L{foo}"), - } - ) - } - ) + swagger= { + "parameters:[", + "{name:'a',in:'path',description:'$L{foo}'},", + "{name:'b',in:'query',description:'$L{foo}'},", + "{in:'body',description:'$L{foo}'},", + "{name:'D',in:'header',description:'$L{foo}'},", + "{name:'a2',in:'path',description:'$L{foo}'},", + "{name:'b2',in:'query',description:'$L{foo}'},", + "{name:'D2',in:'header',description:'$L{foo}'}", + "],", + "responses:{", + "200: {description:'OK'},", + "201: {description:'$L{foo}',headers:{bar:{description:'$L{foo}',type:'string'}}}", + "}" + } ) public String test6(@Path("a") String a, @Query("b") String b, @Body String c, @Header("D") String d, @Path("e") String e, @Query("f") String f, @Header("g") String g) { diff --git a/juneau-microservice/juneau-microservice-test/src/main/java/org/apache/juneau/rest/test/OptionsWithoutNlsResource.java b/juneau-microservice/juneau-microservice-test/src/main/java/org/apache/juneau/rest/test/OptionsWithoutNlsResource.java index 055c62d..023815b 100644 --- a/juneau-microservice/juneau-microservice-test/src/main/java/org/apache/juneau/rest/test/OptionsWithoutNlsResource.java +++ b/juneau-microservice/juneau-microservice-test/src/main/java/org/apache/juneau/rest/test/OptionsWithoutNlsResource.java @@ -22,7 +22,8 @@ import org.apache.juneau.rest.annotation.*; * JUnit automated testcase resource. */ @RestResource( - path="/testOptionsWithoutNls" + path="/testOptionsWithoutNls", + title="test" ) public class OptionsWithoutNlsResource extends BasicRestServlet { private static final long serialVersionUID = 1L; @@ -30,7 +31,7 @@ public class OptionsWithoutNlsResource extends BasicRestServlet { //==================================================================================================== // Should get to the options page without errors //==================================================================================================== - @RestMethod(name=OPTIONS, path="/testOptions/*") + @RestMethod(name=OPTIONS, path="/testOptions/*", description="test") public Swagger testOptions(RestRequest req) { return req.getSwagger(); } @@ -42,5 +43,4 @@ public class OptionsWithoutNlsResource extends BasicRestServlet { public String test(RestRequest req) { return req.getMessage("bad", 1, 2, 3); } - } diff --git a/juneau-microservice/juneau-microservice-test/src/test/java/org/apache/juneau/rest/test/NlsTest.java b/juneau-microservice/juneau-microservice-test/src/test/java/org/apache/juneau/rest/test/NlsTest.java index 1cb00c6..6f5aeb4 100644 --- a/juneau-microservice/juneau-microservice-test/src/test/java/org/apache/juneau/rest/test/NlsTest.java +++ b/juneau-microservice/juneau-microservice-test/src/test/java/org/apache/juneau/rest/test/NlsTest.java @@ -31,7 +31,7 @@ public class NlsTest extends RestTestcase { Swagger s = client.doOptions(URL + "/test1").getResponse(Swagger.class); assertObjectEquals("{title:'Test1.a',description:'Test1.b'}", s.getInfo()); - assertObjectEquals("[{'in':'body',description:'Test1.f'},{'in':'header',name:'D',type:'string',description:'Test1.g'},{'in':'header',name:'D2',type:'string',description:'Test1.j'},{'in':'header',name:'g'},{'in':'path',name:'a',type:'string',description:'Test1.d',required:true},{'in':'path',name:'a2',type:'string',description:'Test1.h',required:true},{'in':'path',name:'e',required:true},{'in':'query',name:'b',type:'string',description:'Test1.e'},{'in':'query',name:'b2',type:'string',des [...] + assertObjectEquals("[{'in':'path',name:'a',type:'string',description:'Test1.d',required:true},{'in':'query',name:'b',type:'string',description:'Test1.e'},{'in':'body',type:'string',description:'Test1.f'},{'in':'header',name:'D',type:'string',description:'Test1.g'},{'in':'path',name:'a2',type:'string',description:'Test1.h',required:true},{'in':'query',name:'b2',type:'string',description:'Test1.i'},{'in':'header',name:'D2',type:'string',description:'Test1.j'},{'in':'path',name:'e',requir [...] assertObjectEquals("{'200':{description:'OK'},'201':{description:'Test1.l',headers:{bar:{description:'Test1.m',type:'string'}}}}", s.getPaths().get("/{a}").get("post").getResponses()); } @@ -43,7 +43,7 @@ public class NlsTest extends RestTestcase { Swagger s = client.doOptions(URL + "/test2").getResponse(Swagger.class); assertObjectEquals("{title:'Test2.a',description:'Test2.b'}", s.getInfo()); - assertObjectEquals("[{'in':'body',description:'Test2.f'},{'in':'header',name:'D',description:'Test2.g'},{'in':'header',name:'D2',description:'Test2.j'},{'in':'header',name:'g'},{'in':'path',name:'a',description:'Test2.d',required:true},{'in':'path',name:'a2',description:'Test2.h',required:true},{'in':'path',name:'e',required:true},{'in':'query',name:'b',description:'Test2.e'},{'in':'query',name:'b2',description:'Test2.i'},{'in':'query',name:'f'}]", s.getPaths().get("/{a}").get("post"). [...] + assertObjectEquals("[{'in':'path',name:'a',description:'Test2.d',required:true},{'in':'query',name:'b',description:'Test2.e'},{'in':'body',description:'Test2.f'},{'in':'header',name:'D',description:'Test2.g'},{'in':'path',name:'a2',description:'Test2.h',required:true},{'in':'query',name:'b2',description:'Test2.i'},{'in':'header',name:'D2',description:'Test2.j'},{'in':'path',name:'e',required:true},{'in':'query',name:'f'},{'in':'header',name:'g'}]", s.getPaths().get("/{a}").get("post"). [...] assertObjectEquals("{'200':{description:'OK2'},'201':{description:'Test2.l'}}", s.getPaths().get("/{a}").get("post").getResponses()); } @@ -55,7 +55,7 @@ public class NlsTest extends RestTestcase { Swagger s = client.doOptions(URL + "/test3").getResponse(Swagger.class); assertObjectEquals("{title:'Test3.a',description:'Test3.b'}", s.getInfo()); - assertObjectEquals("[{'in':'body',description:'Test3.f'},{'in':'header',name:'D',description:'Test3.g'},{'in':'header',name:'D2',description:'Test3.j'},{'in':'header',name:'g'},{'in':'path',name:'a',description:'Test3.d',required:true},{'in':'path',name:'a2',description:'Test3.h',required:true},{'in':'path',name:'e',required:true},{'in':'query',name:'b',description:'Test3.e'},{'in':'query',name:'b2',description:'Test3.i'},{'in':'query',name:'f'}]", s.getPaths().get("/{a}").get("post"). [...] + assertObjectEquals("[{'in':'path',name:'a',description:'Test3.d',required:true},{'in':'query',name:'b',description:'Test3.e'},{'in':'body',description:'Test3.f'},{'in':'header',name:'D',description:'Test3.g'},{'in':'path',name:'a2',description:'Test3.h',required:true},{'in':'query',name:'b2',description:'Test3.i'},{'in':'header',name:'D2',description:'Test3.j'},{'in':'path',name:'e',required:true},{'in':'query',name:'f'},{'in':'header',name:'g'}]", s.getPaths().get("/{a}").get("post"). [...] assertObjectEquals("{'200':{description:'OK3'},'201':{description:'Test3.l'}}", s.getPaths().get("/{a}").get("post").getResponses()); } @@ -67,7 +67,7 @@ public class NlsTest extends RestTestcase { Swagger s = client.doOptions(URL + "/test4").getResponse(Swagger.class); assertObjectEquals("{title:'baz',description:'baz'}", s.getInfo()); - assertObjectEquals("[{'in':'body',description:'baz'},{'in':'header',name:'D',description:'baz'},{'in':'header',name:'D2',description:'baz'},{'in':'header',name:'g'},{'in':'path',name:'a',description:'baz',required:true},{'in':'path',name:'a2',description:'baz',required:true},{'in':'path',name:'e',required:true},{'in':'query',name:'b',description:'baz'},{'in':'query',name:'b2',description:'baz'},{'in':'query',name:'f'}]", s.getPaths().get("/{a}").get("post").getParameters()); + assertObjectEquals("[{'in':'path',name:'a',description:'baz',required:true},{'in':'query',name:'b',description:'baz'},{'in':'body',description:'baz'},{'in':'header',name:'D',description:'baz'},{'in':'path',name:'a2',description:'baz',required:true},{'in':'query',name:'b2',description:'baz'},{'in':'header',name:'D2',description:'baz'},{'in':'path',name:'e',required:true},{'in':'query',name:'f'},{'in':'header',name:'g'}]", s.getPaths().get("/{a}").get("post").getParameters()); assertObjectEquals("{'200':{description:'foobazfoobazfoo'},'201':{description:'baz'}}", s.getPaths().get("/{a}").get("post").getResponses()); } @@ -79,7 +79,7 @@ public class NlsTest extends RestTestcase { Swagger s = client.doOptions(URL + "/test5").getResponse(Swagger.class); assertObjectEquals("{title:'baz2',description:'baz2'}", s.getInfo()); - assertObjectEquals("[{'in':'body',description:'baz2'},{'in':'header',name:'D',description:'baz2'},{'in':'header',name:'D2',description:'baz2'},{'in':'header',name:'g'},{'in':'path',name:'a',description:'baz2',required:true},{'in':'path',name:'a2',description:'baz2',required:true},{'in':'path',name:'e',required:true},{'in':'query',name:'b',description:'baz2'},{'in':'query',name:'b2',description:'baz2'},{'in':'query',name:'f'}]", s.getPaths().get("/{a}").get("post").getParameters()); + assertObjectEquals("[{'in':'path',name:'a',description:'baz2',required:true},{'in':'query',name:'b',description:'baz2'},{'in':'body',description:'baz2'},{'in':'header',name:'D',description:'baz2'},{'in':'path',name:'a2',description:'baz2',required:true},{'in':'query',name:'b2',description:'baz2'},{'in':'header',name:'D2',description:'baz2'},{'in':'path',name:'e',required:true},{'in':'query',name:'f'},{'in':'header',name:'g'}]", s.getPaths().get("/{a}").get("post").getParameters()); assertObjectEquals("{'200':{description:'foobaz2foobaz2foo'},'201':{description:'baz2'}}", s.getPaths().get("/{a}").get("post").getResponses()); } @@ -91,7 +91,7 @@ public class NlsTest extends RestTestcase { Swagger s = client.doOptions(URL + "/test6").getResponse(Swagger.class); assertObjectEquals("{title:'baz',description:'baz'}", s.getInfo()); - assertObjectEquals("[{'in':'body',description:'baz'},{'in':'header',name:'D',type:'string',description:'baz'},{'in':'header',name:'D2',type:'string',description:'baz'},{'in':'header',name:'g'},{'in':'path',name:'a',type:'string',description:'baz',required:true},{'in':'path',name:'a2',type:'string',description:'baz',required:true},{'in':'path',name:'e',required:true},{'in':'query',name:'b',type:'string',description:'baz'},{'in':'query',name:'b2',type:'string',description:'baz'},{'in':'q [...] + assertObjectEquals("[{'in':'path',name:'a',description:'baz',required:true},{'in':'query',name:'b',description:'baz'},{'in':'body',description:'baz'},{'in':'header',name:'D',description:'baz'},{'in':'path',name:'a2',description:'baz',required:true},{'in':'query',name:'b2',description:'baz'},{'in':'header',name:'D2',description:'baz'},{'in':'path',name:'e',required:true},{'in':'query',name:'f'},{'in':'header',name:'g'}]", s.getPaths().get("/{a}").get("post").getParameters()); assertObjectEquals("{'200':{description:'OK'},'201':{description:'baz',headers:{bar:{description:'baz',type:'string'}}}}", s.getPaths().get("/{a}").get("post").getResponses()); } } 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 34a6ea2..3f79a42 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 @@ -12,14 +12,14 @@ // *************************************************************************************************************************** package org.apache.juneau.rest; -import static javax.servlet.http.HttpServletResponse.*; -import static org.apache.juneau.dto.swagger.SwaggerBuilder.*; import static org.apache.juneau.internal.ReflectionUtils.*; +import static org.apache.juneau.internal.StringUtils.*; import java.lang.reflect.Method; import java.util.*; import java.util.concurrent.*; +import org.apache.juneau.*; import org.apache.juneau.dto.swagger.*; import org.apache.juneau.http.*; import org.apache.juneau.internal.*; @@ -27,6 +27,7 @@ import org.apache.juneau.json.*; import org.apache.juneau.parser.*; import org.apache.juneau.rest.annotation.*; import org.apache.juneau.svl.*; +import org.apache.juneau.utils.*; /** * Default implementation of {@link RestInfoProvider}. @@ -46,13 +47,7 @@ public class BasicRestInfoProvider implements RestInfoProvider { private final String siteName, title, - description, - termsOfService, - contact, - license, - version, - tags, - externalDocs; + description; private final ConcurrentHashMap swaggers = new ConcurrentHashMap<>(); /** @@ -67,26 +62,14 @@ public class BasicRestInfoProvider implements RestInfoProvider { this.siteName = b.siteName; this.title = b.title; this.description = b.description; - this.termsOfService = b.termsOfService; - this.contact = b.contact; - this.license = b.license; - this.version = b.version; - this.tags = b.tags; - this.externalDocs = b.externalDocs; } private static final class Builder { String siteName, title, - description, - termsOfService, - contact, - license, - version, - tags, - externalDocs; - + description; + Builder(RestContext context) { LinkedHashMap,RestResource> restResourceAnnotationsParentFirst = findAnnotationsMapParentFirst(RestResource.class, context.getResource().getClass()); @@ -98,49 +81,11 @@ public class BasicRestInfoProvider implements RestInfoProvider { title = r.title(); if (! r.description().isEmpty()) description = r.description(); - ResourceSwagger sr = r.swagger(); - if (! sr.termsOfService().isEmpty()) - termsOfService = sr.termsOfService(); - if (! sr.contact().isEmpty()) - contact = sr.contact(); - if (! sr.license().isEmpty()) - license = sr.license(); - if (! sr.version().isEmpty()) - version = sr.version(); - if (! sr.tags().isEmpty()) - tags = sr.tags(); - if (! sr.externalDocs().isEmpty()) - externalDocs = sr.externalDocs(); } } } /** - * Returns the localized Swagger from the file system. - * - *

    - * Looks for a file called "{ServletClass}_{locale}.json" in the same package as this servlet and returns - * it as a parsed {@link Swagger} object. - * - *

    - * Returned objects are cached per-locale for later quick-lookup. - * - * @param req The incoming HTTP request. - * @return The parsed swagger object, or null if none could be found. - * @throws Exception - * If swagger file was not valid JSON. - */ - public Swagger getSwaggerFromFile(RestRequest req) throws Exception { - Locale locale = req.getLocale(); - Swagger s = swaggers.get(locale); - if (s == null) { - s = context.getClasspathResource(Swagger.class, MediaType.JSON, getClass().getSimpleName() + ".json", locale); - swaggers.putIfAbsent(locale, s == null ? Swagger.NULL : s); - } - return s == Swagger.NULL ? null : s; - } - - /** * Returns the localized swagger for this REST resource. * *

    @@ -155,68 +100,208 @@ public class BasicRestInfoProvider implements RestInfoProvider { @Override /* RestInfoProvider */ public Swagger getSwagger(RestRequest req) throws Exception { - // If a file is defined, use that. - Swagger s = getSwaggerFromFile(req); + Locale locale = req.getLocale(); + + Swagger s = swaggers.get(locale); if (s != null) return s; - s = swagger( - info(getTitle(req), getVersion(req)) - .contact(getContact(req)) - .license(getLicense(req)) - .description(getDescription(req)) - .termsOfService(getTermsOfService(req)) - ) - .consumes(getConsumes(req)) - .produces(getProduces(req)) - .tags(getTags(req)) - .externalDocs(getExternalDocs(req)); + VarResolverSession vr = req.getVarResolverSession(); + JsonParser jp = JsonParser.DEFAULT; + MessageBundle mb = context.getMessages(); + + ObjectMap om = context.getClasspathResource(ObjectMap.class, MediaType.JSON, getClass().getSimpleName() + ".json", locale); + if (om == null) + om = new ObjectMap(); + + LinkedHashMap,RestResource> restResourceAnnotationsParentFirst = findAnnotationsMapParentFirst(RestResource.class, context.getResource().getClass()); + + for (RestResource r : restResourceAnnotationsParentFirst.values()) { + if (r.swagger().length > 0) { + try { + String json = vr.resolve(StringUtils.join(r.swagger(), '\n').trim()); + if (! (json.startsWith("{") && json.endsWith("}"))) + json = "{\n" + json + "\n}"; + om.putAll(new ObjectMap(json)); + } catch (ParseException e) { + throw new ParseException("Malformed swagger JSON encountered in @RestResource(swagger) on class "+context.getResource().getClass().getName()+".").initCause(e); + } + } + } + + String title = this.title; + if (title == null) + title = mb.findFirstString(locale, "title"); + if (title != null) + getInfo(om).put("title", vr.resolve(title)); + + String description = this.description; + if (description == null) + description = mb.findFirstString(locale, "description"); + if (description != null) + getInfo(om).put("description", vr.resolve(description)); + + String version = mb.findFirstString(locale, "version"); + if (version != null) + getInfo(om).put("version", vr.resolve(version)); + + String contact = mb.findFirstString(locale, "contact"); + if (contact != null) + getInfo(om).put("contact", jp.parse(vr.resolve(contact), ObjectMap.class)); + + String license = mb.findFirstString(locale, "license"); + if (license != null) + getInfo(om).put("license", jp.parse(vr.resolve(license), ObjectMap.class)); + + String termsOfService = mb.findFirstString(locale, "termsOfService"); + if (termsOfService != null) + getInfo(om).put("termsOfService", vr.resolve(termsOfService)); + + if (! om.containsKey("consumes")) { + List consumes = req.getContext().getConsumes(); + if (! consumes.isEmpty()) + om.put("consumes", consumes); + } + if (! om.containsKey("produces")) { + List produces = req.getContext().getProduces(); + if (! produces.isEmpty()) + om.put("produces", produces); + } + + String tags = mb.findFirstString(locale, "tags"); + if (tags != null) + om.put("tags", jp.parse(vr.resolve(tags), ObjectList.class)); + + String externalDocs = mb.findFirstString(locale, "externalDocs"); + if (externalDocs != null) + om.put("externalDocs", jp.parse(vr.resolve(externalDocs), ObjectMap.class)); + for (RestJavaMethod sm : context.getCallMethods().values()) { if (sm.isRequestAllowed(req)) { Method m = sm.method; - Operation o = operation() - .operationId(getMethodOperationId(m, req)) - .description(getMethodDescription(m, req)) - .tags(getMethodTags(m, req)) - .summary(getMethodSummary(m, req)) - .externalDocs(getMethodExternalDocs(m, req)) - .parameters(getMethodParameters(m, req)) - .responses(getMethodResponses(m, req)); + RestMethod rm = m.getAnnotation(RestMethod.class); + String mn = m.getName(), cn = m.getClass().getName(); + + ObjectMap mom = getOperation(om, sm.getPathPattern(), sm.getHttpMethod().toLowerCase()); + + if (rm.swagger().length > 0) { + try { + String json = vr.resolve(StringUtils.join(rm.swagger(), '\n').trim()); + if (! (json.startsWith("{") && json.endsWith("}"))) + json = "{\n" + json + "\n}"; + mom.putAll(new ObjectMap(json)); + } catch (ParseException e) { + throw new ParseException("Malformed swagger JSON encountered in @RestMethod(swagger) on method "+mn+" on class "+cn+".").initCause(e); + } + } - if (isDeprecated(m, req)) - o.deprecated(true); + mom.put("operationId", mn); + + String mDescription = rm.description(); + if (mDescription.isEmpty()) + mDescription = mb.findFirstString(locale, mn + ".description"); + if (mDescription != null) + mom.put("description", vr.resolve(mDescription)); + + String mTags = mb.findFirstString(locale, mn + ".tags"); + if (mTags != null) { + mTags = vr.resolve(mTags); + if (StringUtils.isObjectList(mTags)) + mom.put("tags", jp.parse(mTags, ArrayList.class, String.class)); + else + mom.put("tags", Arrays.asList(StringUtils.split(mTags))); + } - o.consumes(getMethodConsumes(m, req)); - o.produces(getMethodProduces(m, req)); + String mSummary = mb.findFirstString(locale, mn + ".summary"); + if (mSummary != null) + mom.put("summary", vr.resolve(mSummary)); - s.path( - sm.getPathPattern(), - sm.getHttpMethod().toLowerCase(), - o - ); + String mExternalDocs = mb.findFirstString(locale, mn + ".externalDocs"); + if (mExternalDocs != null) + mom.put("externalDocs", jp.parse(vr.resolve(s), ObjectMap.class)); + + Map paramMap = new LinkedHashMap<>(); + + ObjectList parameters = mom.getObjectList("parameters"); + if (parameters != null) { + for (ObjectMap param : parameters.elements(ObjectMap.class)) { + String key = param.getString("in") + '.' + param.getString("name"); + paramMap.put(key, param); + } + } + + String mParameters = mb.findFirstString(locale, mn + ".parameters"); + if (mParameters != null) { + ObjectList ol = jp.parse(vr.resolve(mParameters), ObjectList.class); + for (ObjectMap param : ol.elements(ObjectMap.class)) { + String key = param.getString("in") + '.' + param.getString("name"); + if (paramMap.containsKey(key)) + paramMap.get(key).putAll(param); + else + paramMap.put(key, param); + } + } + + // Finally, look for parameters defined on method. + for (RestParam mp : context.getRestParams(m)) { + RestParamType in = mp.getParamType(); + if (in != RestParamType.OTHER) { + String key = in.toString() + '.' + (in == RestParamType.BODY ? null : mp.getName()); + ObjectMap param = new ObjectMap().append("in", in); + if (in != RestParamType.BODY) + param.append("name", mp.name); + if (paramMap.containsKey(key)) { + paramMap.get(key).putAll(param); + } else { + paramMap.put(key, param); + } + } + } + + if (! paramMap.isEmpty()) + mom.put("parameters", paramMap.values()); + + String mResponses = mb.findFirstString(locale, mn + ".responses"); + if (mResponses != null) + mom.put("responses", jp.parse(vr.resolve(mResponses), ObjectMap.class)); + + if (! mom.containsKey("consumes")) { + List mConsumes = req.getParsers().getSupportedMediaTypes(); + if (! mConsumes.equals(om.get("consumes"))) + mom.put("consumes", mConsumes); + } + + if (! mom.containsKey("produces")) { + List mProduces = req.getSerializers().getSupportedMediaTypes(); + if (! mProduces.equals(om.get("produces"))) + mom.put("produces", mProduces); + } } } + s = jp.parse(vr.resolve(om.toString()), Swagger.class); + swaggers.put(locale, s); + return s; } + + private ObjectMap getInfo(ObjectMap om) { + if (! om.containsKey("info")) + om.put("info", new ObjectMap()); + return om.getObjectMap("info"); + } - /** - * Returns the localized operation ID of the specified java method. - * - *

    - * Subclasses can override this method to provide their own operation ID. - * - *

    - * The default implementation simply returns the Java method name. - * - * @param method The Java method annotated with {@link RestMethod @RestMethod}. - * @param req The current request. - * @return The localized operation ID of the method, or null if none was found. - * @throws Exception - */ - public String getMethodOperationId(Method method, RestRequest req) throws Exception { - return method.getName(); + private ObjectMap getOperation(ObjectMap om, String path, String httpMethod) { + if (! om.containsKey("paths")) + om.put("paths", new ObjectMap()); + om = om.getObjectMap("paths"); + if (! om.containsKey(path)) + om.put(path, new ObjectMap()); + om = om.getObjectMap(path); + if (! om.containsKey(httpMethod)) + om.put(httpMethod, new ObjectMap()); + return om.getObjectMap(httpMethod); } /** @@ -266,13 +351,13 @@ public class BasicRestInfoProvider implements RestInfoProvider { VarResolverSession vr = req.getVarResolverSession(); String s = method.getAnnotation(RestMethod.class).summary(); - if (s.isEmpty()) - s = context.getMessages().findFirstString(req.getLocale(), method.getName() + ".summary"); - if (s != null) - return vr.resolve(s); + if (s.isEmpty()) { + Operation o = getSwaggerOperation(method, req); + if (o != null) + s = o.getSummary(); + } - Operation o = getSwaggerOperationFromFile(method, req); - return o == null ? null : o.getSummary(); + return isEmpty(s) ? null : vr.resolve(s); } /** @@ -322,1107 +407,182 @@ public class BasicRestInfoProvider implements RestInfoProvider { VarResolverSession vr = req.getVarResolverSession(); String s = method.getAnnotation(RestMethod.class).description(); - if (s.isEmpty()) - s = context.getMessages().findFirstString(req.getLocale(), method.getName() + ".description"); - if (s != null) - return vr.resolve(s); - - Operation o = getSwaggerOperationFromFile(method, req); - return o == null ? null : o.getDescription(); - } - - /** - * Returns the localized Swagger tags for this Java method. - * - *

    - * Subclasses can override this method to provide their own tags. - * - *

    - * The default implementation returns the value from the following locations (whichever matches first): - *

      - *
    1. {@link MethodSwagger#tags() @MethodSwagger.tags()} annotation. - *
      Examples:
      - *

      - * // Direct value - * @RestMethod( - * swagger=@MethodSwagger(tags="foo,bar,baz") - * ) - * public Object myMethod() {...} - * - * // Pulled from some other location - * @RestMethod( - * swagger=@MethodSwagger(tags="$L{myLocalizedTags}") - * ) - * public Object myMethod() {...} - *

      - *
    2. Localized string from resource bundle identified by {@link RestResource#messages() @RestResource.messages()} - * on the resource class, then any parent classes. - *
        - *
      1. [ClassName].[javaMethodName].tags - *
      2. [javaMethodName].tags - *
      - *
      Value can be a comma-delimited list or JSON array. - *
      Value can contain any SVL variables defined on the {@link MethodSwagger#tags() @MethodSwagger.tags()} annotation. - *
      Examples:
      - *

      - * // Comma-delimited list - * MyClass.myMethod.tags = foo, bar, baz - * - * // JSON array - * MyClass.myMethod.tags = ["foo", "bar", "baz"] - * - * // Pulled from some other location - * MyClass.myMethod.description = $C{MyStrings/MyClass.myMethod.tags} - *

      - *
    - * - * @param method The Java method annotated with {@link RestMethod @RestMethod}. - * @param req The current request. - * @return The localized tags of the method, or null if none were found. - * @throws Exception - */ - public List getMethodTags(Method method, RestRequest req) throws Exception { - JsonParser p = JsonParser.DEFAULT; - VarResolverSession vr = req.getVarResolverSession(); - - String s = method.getAnnotation(RestMethod.class).swagger().tags(); - if (s.isEmpty()) - s = context.getMessages().findFirstString(req.getLocale(), method.getName() + ".tags"); - if (s != null) { - s = vr.resolve(s); - if (StringUtils.isObjectList(s)) - return p.parse(s, ArrayList.class, String.class); - return Arrays.asList(StringUtils.split(s)); + if (s.isEmpty()) { + Operation o = getSwaggerOperation(method, req); + if (o != null) + s = o.getDescription(); } - - Operation o = getSwaggerOperationFromFile(method, req); - return o == null ? null : o.getTags(); + + return isEmpty(s) ? null : vr.resolve(s); } /** - * Returns the localized external documentation of the specified java method on this servlet. + * Returns the localized site name of this REST resource. * *

    - * Subclasses can override this method to provide their own external documentation. + * Subclasses can override this method to provide their own site name. * *

    * The default implementation returns the value from the following locations (whichever matches first): *

      - *
    1. {@link MethodSwagger#externalDocs() @MethodSwagger.externalDocs()} annotation. + *
    2. {@link RestResource#siteName() @RestResource.siteName()} annotation on this class, and then any parent classes. *
      Examples:
      *

      - * // Direct value - * @RestMethod( - * swagger=@MethodSwagger(externalDocs="{description:'Find more info here',url:'https://swagger.io'}") - * ) - * public Object myMethod() {...} + * // Direct value + * @RestResource(siteName="My Site") + * public class MyResource {...} * - * // Pulled from some other location - * @RestMethod( - * swagger=@MethodSwagger(externalDocs="$L{myLocalizedExternalDocs}") - * ) - * public Object myMethod() {...} + * // Pulled from some other location + * @RestResource(siteName="$L{myLocalizedSiteName}") + * public class MyResource {...} *

      - *
    3. Localized string from resource bundle identified by {@link RestResource#messages() @RestResource.messages()} + *
    4. Localized strings from resource bundle identified by {@link RestResource#messages() @RestResource.messages()} * on the resource class, then any parent classes. *
        - *
      1. [ClassName].[javaMethodName].externalDocs - *
      2. [javaMethodName].externalDocs + *
      3. [ClassName].siteName + *
      4. siteName *
      - *
      Value is a JSON representation of a {@link ExternalDocumentation} object. - *
      Value can contain any SVL variables defined on the {@link MethodSwagger#externalDocs() @MethodSwagger.externalDocs()} annotation. + *
      Value can contain any SVL variables defined on the {@link RestResource#siteName() @RestResource.siteName()} annotation. *
      Examples:
      *

      * // Direct value - * MyClass.myMethod.externalDocs = {description:"Find more info here",url:"https://swagger.io"} + * MyClass.siteName = My Site * * // Pulled from some other location - * MyClass.myMethod.externalDocs = $C{MyStrings/MyClass.myMethod.externalDocs} + * MyClass.siteName = $C{MyStrings/MyClass.siteName} *

      *
    * - * @param method The Java method annotated with {@link RestMethod @RestMethod}. * @param req The current request. - * @return The localized external documentation of the method, or null if none was found. + * @return The localized site name of this REST resource, or null if none was found. * @throws Exception */ - public ExternalDocumentation getMethodExternalDocs(Method method, RestRequest req) throws Exception { - JsonParser p = JsonParser.DEFAULT; + @Override /* RestInfoProvider */ + public String getSiteName(RestRequest req) throws Exception { VarResolverSession vr = req.getVarResolverSession(); - - String s = method.getAnnotation(RestMethod.class).swagger().externalDocs(); - if (s.isEmpty()) - s = context.getMessages().findFirstString(req.getLocale(), method.getName() + ".externalDocs"); - if (s != null) - return p.parse(vr.resolve(s), ExternalDocumentation.class); - - Operation o = getSwaggerOperationFromFile(method, req); - return o == null ? null : o.getExternalDocs(); + if (siteName != null) + return vr.resolve(siteName); + String siteName = context.getMessages().findFirstString(req.getLocale(), "siteName"); + if (siteName != null) + return vr.resolve(siteName); + return null; } - + /** - * Returns the localized parameter info for the specified java method. + * Returns the localized title of this REST resource. * *

    - * Subclasses can override this method to provide their own parameter info. + * Subclasses can override this method to provide their own title. * *

    * The default implementation returns the value from the following locations (whichever matches first): *

      - *
    1. Operation information from swagger file. - *
    2. {@link MethodSwagger#parameters() @MethodSwagger.parameters()} annotation. + *
    3. {@link RestResource#title() @RestResource.siteName()} annotation on this class, and then any parent classes. *
      Examples:
      *

      - * // Direct value - * @RestMethod( - * swagger=@MethodSwagger( - * parameters={ - * @Parameter(in="path", name="a", description="The 'a' attribute") - * } - * ) - * ) - * public Object myMethod() {...} + * // Direct value + * @RestResource(title="My Resource") + * public class MyResource {...} * - * // Pulled from some other location - * @RestMethod( - * swagger=@MethodSwagger( - * parameters={ - * @Parameter(in="path", name="a", description="$L{myLocalizedParamADescription}") - * } - * ) - * ) - * public Object myMethod() {...} + * // Pulled from some other location + * @RestResource(title="$L{myLocalizedTitle}") + * public class MyResource {...} *

      *
    4. Localized strings from resource bundle identified by {@link RestResource#messages() @RestResource.messages()} * on the resource class, then any parent classes. *
        - *
      1. [ClassName].[javaMethodName].parameters - *
      2. [javaMethodName].parameters + *
      3. [ClassName].title + *
      4. title *
      - *
      Value is a JSON representation of a {@link ParameterInfo}[] object. - *
      Value can contain any SVL variables defined on the {@link MethodSwagger#parameters() @MethodSwagger.parameters()} annotation. + *
      Value can contain any SVL variables defined on the {@link RestResource#title() @RestResource.title()} annotation. *
      Examples:
      *

      * // Direct value - * MyClass.myMethod.parameters = [{name:"a",in:"path",description:"The ''a'' attribute"}] + * MyClass.title = My Resource * * // Pulled from some other location - * MyClass.myMethod.parameters = $C{MyStrings/MyClass.myMethod.parameters} + * MyClass.title = $C{MyStrings/MyClass.title} *

      - *
    5. Information gathered directly from the parameters on the Java method. + *
    6. /info/title entry in swagger file. *
    * - * @param method The Java method annotated with {@link RestMethod @RestMethod}. * @param req The current request. - * @return The localized parameter info of the method, or null if none was found. + * @return The localized title of this REST resource, or null if none was found. * @throws Exception */ - public List getMethodParameters(Method method, RestRequest req) throws Exception { - - Operation o = getSwaggerOperationFromFile(method, req); - if (o != null && o.getParameters() != null) - return o.getParameters(); - + @Override /* RestInfoProvider */ + public String getTitle(RestRequest req) throws Exception { VarResolverSession vr = req.getVarResolverSession(); - JsonParser jp = JsonParser.DEFAULT; - Map m = new TreeMap<>(); - - // First parse @RestMethod.parameters() annotation. - for (org.apache.juneau.rest.annotation.Parameter v : method.getAnnotation(RestMethod.class).swagger().parameters()) { - String in = vr.resolve(v.in()); - ParameterInfo p = parameterInfo(in, vr.resolve(v.name())); - - if (! v.description().isEmpty()) - p.description(vr.resolve(v.description())); - if (v.required()) - p.required(v.required()); - - if ("body".equals(in)) { - if (! v.schema().isEmpty()) - p.schema(jp.parse(vr.resolve(v.schema()), SchemaInfo.class)); - } else { - if (v.allowEmptyValue()) - p.allowEmptyValue(v.allowEmptyValue()); - if (! v.collectionFormat().isEmpty()) - p.collectionFormat(vr.resolve(v.collectionFormat())); - if (! v._default().isEmpty()) - p._default(vr.resolve(v._default())); - if (! v.format().isEmpty()) - p.format(vr.resolve(v.format())); - if (! v.items().isEmpty()) - p.items(jp.parse(vr.resolve(v.items()), Items.class)); - p.type(vr.resolve(v.type())); - } - m.put(p.getIn() + '.' + p.getName(), p); - } - - // Next, look in resource bundle. - String s = context.getMessages().findFirstString(req.getLocale(), method.getName() + ".parameters"); - if (s != null) { - for (ParameterInfo pi : jp.parse(vr.resolve(s), ParameterInfo[].class)) { - String key = pi.getIn() + '.' + pi.getName(); - ParameterInfo p = m.get(key); - if (p == null) - m.put(key, pi); - else - p.copyFrom(pi); - } - } - - // Finally, look for parameters defined on method. - for (RestParam mp : context.getRestParams(method)) { - RestParamType in = mp.getParamType(); - if (in != RestParamType.OTHER) { - String k2 = in.toString() + '.' + (in == RestParamType.BODY ? null : mp.getName()); - ParameterInfo p = m.get(k2); - if (p == null) { - p = parameterInfoStrict(in.toString(), mp.getName()); - m.put(k2, p); - } - } - } - - return m.isEmpty() ? null : new ArrayList<>(m.values()); + if (title != null) + return vr.resolve(title); + String title = context.getMessages().findFirstString(req.getLocale(), "title"); + if (title != null) + return vr.resolve(title); + Swagger s = getSwagger(req); + if (s != null && s.getInfo() != null) + return s.getInfo().getTitle(); + return null; } /** - * Returns the localized response info for the specified java method. + * Returns the localized description of this REST resource. * *

    - * Subclasses can override this method to provide their own parameter info. + * Subclasses can override this method to provide their own description. * *

    * The default implementation returns the value from the following locations (whichever matches first): *

      - *
    1. Operation information from swagger file. - *
    2. {@link MethodSwagger#responses() @MethodSwagger.responses()} annotation. + *
    3. {@link RestResource#description() @RestResource.description()} annotation on this class, and then any parent classes. *
      Examples:
      *

      - * // Direct value - * @RestMethod( - * swagger=@MethodSwagger( - * responses={ - * @Response( - * value=302, - * description="Thing wasn't found here", - * headers={ - * @Parameter(name="Location", description="The place to find the thing") - * } - * ) - * } - * ) - * ) - * public Object myMethod() {...} + * // Direct value + * @RestResource(description="My Resource") + * public class MyResource {...} * - * // Pulled from some other location - * @RestMethod( - * swagger=@MethodSwagger( - * responses={ - * @Response( - * value=302, - * description="Thing wasn't found here", - * headers={ - * @Parameter(name="Location", description="$L{myLocalizedResponseDescription}") - * } - * ) - * } - * ) - * ) - * public Object myMethod() {...} + * // Pulled from some other location + * @RestResource(description="$L{myLocalizedDescription}") + * public class MyResource {...} *

      *
    4. Localized strings from resource bundle identified by {@link RestResource#messages() @RestResource.messages()} * on the resource class, then any parent classes. *
        - *
      1. [ClassName].[javaMethodName].responses - *
      2. [javaMethodName].responses + *
      3. [ClassName].description + *
      4. description *
      - *
      Value is a JSON representation of a Map<Integer,{@link ResponseInfo}> object. - *
      Value can contain any SVL variables defined on the {@link MethodSwagger#responses() @MethodSwagger.responses()} annotation. + *
      Value can contain any SVL variables defined on the {@link RestResource#description() @RestResource.description()} annotation. *
      Examples:
      *

      * // Direct value - * MyClass.myMethod.responses = {302:{description:'Thing wasn''t found here',headers={Location:{description:"The place to find the thing"}}} + * MyClass.description = My Resource * * // Pulled from some other location - * MyClass.myMethod.responses = $C{MyStrings/MyClass.myMethod.responses} + * MyClass.description = $C{MyStrings/MyClass.description} *

      - *
    5. Information gathered directly from the parameters on the Java method. + *
    6. /info/description entry in swagger file. *
    * - * @param method The Java method annotated with {@link RestMethod @RestMethod}. * @param req The current request. - * @return The localized response info of the method, or null if none was found. + * @return The localized description of this REST resource, or null if none was was found. * @throws Exception */ - @SuppressWarnings("unchecked") - public Map getMethodResponses(Method method, RestRequest req) throws Exception { - - Operation o = getSwaggerOperationFromFile(method, req); - if (o != null && o.getResponses() != null) - return o.getResponses(); - + @Override /* RestInfoProvider */ + public String getDescription(RestRequest req) throws Exception { VarResolverSession vr = req.getVarResolverSession(); - JsonParser jp = JsonParser.DEFAULT; - Map m = new TreeMap<>(); - Map m2 = new TreeMap<>(); - - // First parse @RestMethod.parameters() annotation. - for (Response r : method.getAnnotation(RestMethod.class).swagger().responses()) { - int httpCode = r.value(); - String description = r.description().isEmpty() ? RestUtils.getHttpResponseText(r.value()) : vr.resolve(r.description()); - ResponseInfo r2 = responseInfo(description); - - if (r.headers().length > 0) { - for (org.apache.juneau.rest.annotation.Parameter v : r.headers()) { - HeaderInfo h = headerInfoStrict(vr.resolve(v.type())); - if (! v.collectionFormat().isEmpty()) - h.collectionFormat(vr.resolve(v.collectionFormat())); - if (! v._default().isEmpty()) - h._default(vr.resolve(v._default())); - if (! v.description().isEmpty()) - h.description(vr.resolve(v.description())); - if (! v.format().isEmpty()) - h.format(vr.resolve(v.format())); - if (! v.items().isEmpty()) - h.items(jp.parse(vr.resolve(v.items()), Items.class)); - r2.header(v.name(), h); - m2.put(httpCode + '.' + v.name(), h); - } - } - m.put(httpCode, r2); - } - - // Next, look in resource bundle. - String s = context.getMessages().findFirstString(req.getLocale(), method.getName() + ".responses"); - if (s != null) { - for (Map.Entry e : ((Map)jp.parse(vr.resolve(s), Map.class, Integer.class, ResponseInfo.class)).entrySet()) { - Integer httpCode = e.getKey(); - ResponseInfo ri = e.getValue(); - - ResponseInfo r = m.get(httpCode); - if (r == null) - m.put(httpCode, ri); - else - r.copyFrom(ri); - } - } - - return m.isEmpty() ? null : m; + if (description != null) + return vr.resolve(description); + String description = context.getMessages().findFirstString(req.getLocale(), "description"); + if (description != null) + return vr.resolve(description); + Swagger s = getSwagger(req); + if (s != null && s.getInfo() != null) + return s.getInfo().getDescription(); + return null; } - /** - * Returns the supported Accept types the specified Java method. - * - *

    - * Subclasses can override this method to provide their own produces info. - * - *

    - * The default implementation returns the value from the following locations (whichever matches first): - *

      - *
    1. {@link RestMethod#produces() @RestMethod.supportedAcceptTypes()} annotation. - *
      Examples:
      - *

      - * // Direct value - * @RestMethod(supportedAcceptTypes={"text/json"}) - * public Object myMethod() {...} - * - * // Pulled from some other location - * @RestMethod(supportedAcceptTypes={"$C{mySupportedProduces}"}) - * public Object myMethod() {...} - *

      - *
    2. Media types defined on the parsers associated with the method. - *
    - * - * @param method The Java method annotated with {@link RestMethod @RestMethod}. - * @param req The current request. - * @return The supported Accept types of the method, or null if none was found - * or the list of media types match those of the parent resource class. - * @throws Exception - */ - public List getMethodProduces(Method method, RestRequest req) throws Exception { - VarResolverSession vr = req.getVarResolverSession(); - String[] s = method.getAnnotation(RestMethod.class).produces(); - if (s.length > 0) - return Arrays.asList(MediaType.forStrings(vr.resolve(s))); - List l = req.getSerializers().getSupportedMediaTypes(); - return (l.equals(context.getProduces()) ? null : l); - } - - /** - * Returns the supported Content-Type types the specified Java method. - * - *

    - * The default implementation returns the value from the following locations (whichever matches first): - *

      - *
    1. {@link RestMethod#consumes() @RestMethod.supportedContentTypes()} annotation. - *
      Examples:
      - *

      - * // Direct value - * @RestMethod(supportedContentTypes={"text/json"}) - * public Object myMethod() {...} - * - * // Pulled from some other location - * @RestMethod(supportedContentTypes={"$C{mySupportedConsumes}"}) - * public Object myMethod() {...} - *

      - *
    2. Media types defined on the serializers associated with the method. - *
    - * - * @param method The Java method annotated with {@link RestMethod @RestMethod}. - * @param req The current request. - * @return The supported Content-Type types of the method, or null if none was found - * or the list of media types match those of the parent resource class. - * @throws Exception - */ - public List getMethodConsumes(Method method, RestRequest req) throws Exception { - VarResolverSession vr = req.getVarResolverSession(); - String[] s = method.getAnnotation(RestMethod.class).consumes(); - if (s.length > 0) - return Arrays.asList(MediaType.forStrings(vr.resolve(s))); - List l = req.getParsers().getSupportedMediaTypes(); - return (l.equals(context.getConsumes()) ? null : l); - } - - /** - * Returns whether the specified method is deprecated - * - *

    - * The default implementation returns the value from the following location: - *

      - *
    1. {@link MethodSwagger#deprecated() @MethodSwagger.deprecated()} annotation. - *
      Examples:
      - *

      - * @RestMethod( - * swagger=@MethodSwagger( - * deprecated=true - * ) - * ) - * public Object myMethod() {...} - *

      - *
    - * - * @param method The Java method annotated with {@link RestMethod @RestMethod}. - * @param req The current request. - * @return true if the method is deprecated. - * @throws Exception - */ - public boolean isDeprecated(Method method, RestRequest req) throws Exception { - return method.getAnnotation(RestMethod.class).swagger().deprecated(); - } - - /** - * Returns the localized site name of this REST resource. - * - *

    - * Subclasses can override this method to provide their own site name. - * - *

    - * The default implementation returns the value from the following locations (whichever matches first): - *

      - *
    1. {@link RestResource#siteName() @RestResource.siteName()} annotation on this class, and then any parent classes. - *
      Examples:
      - *

      - * // Direct value - * @RestResource(siteName="My Site") - * public class MyResource {...} - * - * // Pulled from some other location - * @RestResource(siteName="$L{myLocalizedSiteName}") - * public class MyResource {...} - *

      - *
    2. Localized strings from resource bundle identified by {@link RestResource#messages() @RestResource.messages()} - * on the resource class, then any parent classes. - *
        - *
      1. [ClassName].siteName - *
      2. siteName - *
      - *
      Value can contain any SVL variables defined on the {@link RestResource#siteName() @RestResource.siteName()} annotation. - *
      Examples:
      - *

      - * // Direct value - * MyClass.siteName = My Site - * - * // Pulled from some other location - * MyClass.siteName = $C{MyStrings/MyClass.siteName} - *

      - *
    - * - * @param req The current request. - * @return The localized site name of this REST resource, or null if none was found. - * @throws Exception - */ - @Override /* RestInfoProvider */ - public String getSiteName(RestRequest req) throws Exception { - VarResolverSession vr = req.getVarResolverSession(); - if (siteName != null) - return vr.resolve(siteName); - String siteName = context.getMessages().findFirstString(req.getLocale(), "siteName"); - if (siteName != null) - return vr.resolve(siteName); - return null; - } - - /** - * Returns the localized title of this REST resource. - * - *

    - * Subclasses can override this method to provide their own title. - * - *

    - * The default implementation returns the value from the following locations (whichever matches first): - *

      - *
    1. {@link RestResource#title() @RestResource.siteName()} annotation on this class, and then any parent classes. - *
      Examples:
      - *

      - * // Direct value - * @RestResource(title="My Resource") - * public class MyResource {...} - * - * // Pulled from some other location - * @RestResource(title="$L{myLocalizedTitle}") - * public class MyResource {...} - *

      - *
    2. Localized strings from resource bundle identified by {@link RestResource#messages() @RestResource.messages()} - * on the resource class, then any parent classes. - *
        - *
      1. [ClassName].title - *
      2. title - *
      - *
      Value can contain any SVL variables defined on the {@link RestResource#title() @RestResource.title()} annotation. - *
      Examples:
      - *

      - * // Direct value - * MyClass.title = My Resource - * - * // Pulled from some other location - * MyClass.title = $C{MyStrings/MyClass.title} - *

      - *
    3. /info/title entry in swagger file. - *
    - * - * @param req The current request. - * @return The localized title of this REST resource, or null if none was found. - * @throws Exception - */ - @Override /* RestInfoProvider */ - public String getTitle(RestRequest req) throws Exception { - VarResolverSession vr = req.getVarResolverSession(); - if (title != null) - return vr.resolve(title); - String title = context.getMessages().findFirstString(req.getLocale(), "title"); - if (title != null) - return vr.resolve(title); - Swagger s = getSwaggerFromFile(req); - if (s != null && s.getInfo() != null) - return s.getInfo().getTitle(); - return null; - } - - /** - * Returns the localized description of this REST resource. - * - *

    - * Subclasses can override this method to provide their own description. - * - *

    - * The default implementation returns the value from the following locations (whichever matches first): - *

      - *
    1. {@link RestResource#description() @RestResource.description()} annotation on this class, and then any parent classes. - *
      Examples:
      - *

      - * // Direct value - * @RestResource(description="My Resource") - * public class MyResource {...} - * - * // Pulled from some other location - * @RestResource(description="$L{myLocalizedDescription}") - * public class MyResource {...} - *

      - *
    2. Localized strings from resource bundle identified by {@link RestResource#messages() @RestResource.messages()} - * on the resource class, then any parent classes. - *
        - *
      1. [ClassName].description - *
      2. description - *
      - *
      Value can contain any SVL variables defined on the {@link RestResource#description() @RestResource.description()} annotation. - *
      Examples:
      - *

      - * // Direct value - * MyClass.description = My Resource - * - * // Pulled from some other location - * MyClass.description = $C{MyStrings/MyClass.description} - *

      - *
    3. /info/description entry in swagger file. - *
    - * - * @param req The current request. - * @return The localized description of this REST resource, or null if none was was found. - * @throws Exception - */ - @Override /* RestInfoProvider */ - public String getDescription(RestRequest req) throws Exception { - VarResolverSession vr = req.getVarResolverSession(); - if (description != null) - return vr.resolve(description); - String description = context.getMessages().findFirstString(req.getLocale(), "description"); - if (description != null) - return vr.resolve(description); - Swagger s = getSwaggerFromFile(req); - if (s != null && s.getInfo() != null) - return s.getInfo().getDescription(); - return null; - } - - /** - * Returns the localized contact information of this REST resource. - * - *

    - * Subclasses can override this method to provide their own contact information. - * - *

    - * The default implementation returns the value from the following locations (whichever matches first): - *

      - *
    1. {@link ResourceSwagger#contact() @ResourceSwagger.contact()} annotation on this class, and then any parent classes. - *
      Examples:
      - *

      - * // Direct value - * @RestResource( - * swagger=@ResourceSwagger(contact="{name:'John Smith',email:'john.smith@foo.bar'}") - * ) - * public class MyResource {...} - * - * // Pulled from some other location - * @RestResource( - * swagger=@ResourceSwagger(contact="$C{MyStrings/MyClass.myContactInfo}") - * ) - * public class MyResource {...} - *

      - *
    2. Localized strings from resource bundle identified by {@link RestResource#messages() @RestResource.messages()} - * on the resource class, then any parent classes. - *
        - *
      1. [ClassName].contact - *
      2. contact - *
      - *
      Value can contain any SVL variables defined on the {@link ResourceSwagger#contact() @ResourceSwagger.contact()} annotation. - *
      Examples:
      - *

      - * // Direct value - * MyClass.contact = {name:"John Smith",email:"john.smith@foo.bar"} - * - * // Pulled from some other location - * MyClass.contact = $C{MyStrings/MyClass.myContactInfo} - *

      - *
    3. /info/contact entry in swagger file. - *
    - * - * @param req The current request. - * @return - * The localized contact information of this REST resource, or null if none was found. - * @throws Exception - */ - public Contact getContact(RestRequest req) throws Exception { - VarResolverSession vr = req.getVarResolverSession(); - JsonParser jp = JsonParser.DEFAULT; - try { - if (contact != null) - return jp.parse(vr.resolve(contact), Contact.class); - String contact = context.getMessages().findFirstString(req.getLocale(), "contact"); - if (contact != null) - return jp.parse(vr.resolve(contact), Contact.class); - Swagger s = getSwaggerFromFile(req); - if (s != null && s.getInfo() != null) - return s.getInfo().getContact(); - return null; - } catch (ParseException e) { - throw new RestException(SC_INTERNAL_SERVER_ERROR, e); - } - } - - /** - * Returns the localized license information of this REST resource. - * - *

    - * Subclasses can override this method to provide their own license information. - * - *

    - * The default implementation returns the value from the following locations (whichever matches first): - *

      - *
    1. {@link ResourceSwagger#license() @ResourceSwagger.license()} annotation on this class, and then any parent classes. - *
      Examples:
      - *

      - * // Direct value - * @RestResource( - * swagger=@ResourceSwagger(license="{name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'}") - * ) - * public class MyResource {...} - * - * // Pulled from some other location - * @RestResource( - * swagger=@ResourceSwagger(license="$C{MyStrings/MyClass.myLicenseInfo}") - * ) - * public class MyResource {...} - *

      - *
    2. Localized strings from resource bundle identified by {@link RestResource#messages() @RestResource.messages()} - * on the resource class, then any parent classes. - *
        - *
      1. [ClassName].license - *
      2. license - *
      - *
      Value can contain any SVL variables defined on the {@link ResourceSwagger#license() @ResourceSwagger.license()} annotation. - *
      Examples:
      - *

      - * // Direct value - * MyClass.license = {name:"Apache 2.0",url:"http://www.apache.org/licenses/LICENSE-2.0.html"} - * - * // Pulled from some other location - * MyClass.license = $C{MyStrings/MyClass.myLicenseInfo} - *

      - *
    3. /info/license entry in swagger file. - *
    - * - * @param req The current request. - * @return - * The localized license information of this REST resource, or null if none was found found. - * @throws Exception - */ - public License getLicense(RestRequest req) throws Exception { - VarResolverSession vr = req.getVarResolverSession(); - JsonParser jp = JsonParser.DEFAULT; - try { - if (license != null) - return jp.parse(vr.resolve(license), License.class); - String license = context.getMessages().findFirstString(req.getLocale(), "license"); - if (license != null) - return jp.parse(vr.resolve(license), License.class); - Swagger s = getSwaggerFromFile(req); - if (s != null && s.getInfo() != null) - return s.getInfo().getLicense(); - return null; - } catch (ParseException e) { - throw new RestException(SC_INTERNAL_SERVER_ERROR, e); - } - } - - /** - * Returns the terms-of-service information of this REST resource. - * - *

    - * Subclasses can override this method to provide their own terms-of-service information. - * - *

    - * The default implementation returns the value from the following locations (whichever matches first): - *

      - *
    1. {@link ResourceSwagger#termsOfService() @ResourceSwagger.termsOfService()} annotation on this class, and then any parent classes. - *
      Examples:
      - *

      - * // Direct value - * @RestResource( - * swagger=@ResourceSwagger(termsOfService="You're on your own") - * ) - * public class MyResource {...} - * - * // Pulled from some other location - * @RestResource( - * swagger=@ResourceSwagger(termsOfService="$C{MyStrings/MyClass.myTermsOfService}") - * ) - * public class MyResource {...} - *

      - *
    2. Localized strings from resource bundle identified by {@link RestResource#messages() @RestResource.messages()} - * on the resource class, then any parent classes. - *
        - *
      1. [ClassName].termsOfService - *
      2. termsOfService - *
      - *
      Value can contain any SVL variables defined on the {@link ResourceSwagger#termsOfService() @ResourceSwagger.termsOfService()} annotation. - *
      Examples:
      - *

      - * // Direct value - * MyClass.termsOfService = You''re on your own - * - * // Pulled from some other location - * MyClass.termsOfService = $C{MyStrings/MyClass.myTermsOfService} - *

      - *
    3. /info/termsOfService entry in swagger file. - *
    - * - * @param req The current request. - * @return - * The localized terms-of-service of this REST resource, or null if none was found. - * @throws Exception - */ - public String getTermsOfService(RestRequest req) throws Exception { - VarResolverSession vr = req.getVarResolverSession(); - if (termsOfService != null) - return vr.resolve(termsOfService); - String termsOfService = context.getMessages().findFirstString(req.getLocale(), "termsOfService"); - if (termsOfService != null) - return vr.resolve(termsOfService); - Swagger s = getSwaggerFromFile(req); - if (s != null && s.getInfo() != null) - return s.getInfo().getTermsOfService(); - return null; - } - - /** - * Returns the version information of this REST resource. - * - *

    - * Subclasses can override this method to provide their own version information. - * - *

    - * The default implementation returns the value from the following locations (whichever matches first): - *

      - *
    1. {@link ResourceSwagger#version() @ResourceSwagger.version()} annotation on this class, and then any parent classes. - *
      Examples:
      - *

      - * // Direct value - * @RestResource( - * swagger=@ResourceSwagger(version="2.0") - * ) - * public class MyResource {...} - * - * // Pulled from some other location - * @RestResource( - * swagger=@ResourceSwagger(version="$C{MyStrings/MyClass.myVersion}") - * ) - * public class MyResource {...} - *

      - *
    2. Localized strings from resource bundle identified by {@link RestResource#messages() @RestResource.messages()} - * on the resource class, then any parent classes. - *
        - *
      1. [ClassName].version - *
      2. version - *
      - *
      Value can contain any SVL variables defined on the {@link ResourceSwagger#version() @ResourceSwagger.version()} annotation. - *
      Examples:
      - *

      - * // Direct value - * MyClass.version = 2.0 - * - * // Pulled from some other location - * MyClass.version = $C{MyStrings/MyClass.myVersion} - *

      - *
    3. /info/version entry in swagger file. - *
    - * - * @param req The current request. - * @return - * The localized version of this REST resource, or null if none was found. - * @throws Exception - */ - public String getVersion(RestRequest req) throws Exception { - VarResolverSession vr = req.getVarResolverSession(); - if (version != null) - return vr.resolve(version); - String version = context.getMessages().findFirstString(req.getLocale(), "version"); - if (version != null) - return vr.resolve(version); - Swagger s = getSwaggerFromFile(req); - if (s != null && s.getInfo() != null) - return s.getInfo().getVersion(); - return null; - } - - /** - * Returns the supported Content-Type request headers for the REST resource. - *

    - * The default implementation returns the value from the following locations (whichever matches first): - *

      - *
    1. {@link ResourceSwagger#version() @ResourceSwagger.version()} annotation on this class, and then any parent classes. - *
      Examples:
      - *

      - * // Direct value - * @RestResource( - * swagger=@ResourceSwagger(version="2.0") - * ) - * public class MyResource {...} - * - * // Pulled from some other location - * @RestResource( - * swagger=@ResourceSwagger(version="$C{MyStrings/MyClass.myVersion}") - * ) - * public class MyResource {...} - *

      - *
    2. Localized strings from resource bundle identified by {@link RestResource#messages() @RestResource.messages()} - * on the resource class, then any parent classes. - *
        - *
      1. [ClassName].version - *
      2. version - *
      - *
      Value can contain any SVL variables defined on the {@link ResourceSwagger#version() @ResourceSwagger.version()} annotation. - *
      Examples:
      - *

      - * // Direct value - * MyClass.version = 2.0 - * - * // Pulled from some other location - * MyClass.version = $C{MyStrings/MyClass.myVersion} - *

      - *
    3. /info/version entry in swagger file. - *
    - * - * @param req The current request. - * @return - * The supported Content-Type request headers of the REST resource, or null if none were found. - * @throws Exception - */ - public List getConsumes(RestRequest req) throws Exception { - List l = req.getContext().getConsumes(); - return l.isEmpty() ? null : l; - } - - /** - * Returns the supported Accept request headers for the REST resource. - * - * @param req The current request. - * @return - * The supported Accept request headers of the REST resource, or null if none were found. - * @throws Exception - */ - public List getProduces(RestRequest req) throws Exception { - List l = req.getContext().getProduces(); - return l.isEmpty() ? null : l; - } - - /** - * Returns the version information of this REST resource. - * - *

    - * Subclasses can override this method to provide their own version information. - * - *

    - * The default implementation returns the value from the following locations (whichever matches first): - *

      - *
    1. {@link ResourceSwagger#tags() @ResourceSwagger.tags()} annotation on this class, and then any parent classes. - *
      Examples:
      - *

      - * // Direct value - * @RestResource( - * swagger=@ResourceSwagger(tags="foo,bar,baz") - * ) - * public class MyResource {...} - * - * // Pulled from some other location - * @RestResource( - * swagger=@ResourceSwagger(tags="$C{MyStrings/MyClass.myTags}") - * ) - * public class MyResource {...} - *

      - *
    2. Localized strings from resource bundle identified by {@link RestResource#messages() @RestResource.messages()} - * on the resource class, then any parent classes. - *
        - *
      1. [ClassName].tags - *
      2. tags - *
      - *
      Value is either a comma-delimited list or a JSON array. - *
      Value can contain any SVL variables defined on the {@link ResourceSwagger#tags() @ResourceSwagger.tags()} annotation. - *
      Examples:
      - *

      - * // Comma-delimited list - * MyClass.tags = foo,bar,baz - * - * // JSON array - * MyClass.tags = ["foo","bar","baz"] - * - * // Pulled from some other location - * MyClass.tags = $C{MyStrings/MyClass.myTags} - *

      - *
    3. tags entry in swagger file. - *
    - * - * @param req The current request. - * @return - * The localized tags of this REST resource, or null if none was found. - * @throws Exception - */ - public List getTags(RestRequest req) throws Exception { - VarResolverSession vr = req.getVarResolverSession(); - JsonParser jp = JsonParser.DEFAULT; - try { - if (tags != null) - return jp.parse(vr.resolve(tags), ArrayList.class, Tag.class); - String tags = context.getMessages().findFirstString(req.getLocale(), "tags"); - if (tags != null) - return jp.parse(vr.resolve(tags), ArrayList.class, Tag.class); - Swagger s = getSwaggerFromFile(req); - if (s != null && s.getTags() != null) - return s.getTags(); - return null; - } catch (Exception e) { - throw new RestException(SC_INTERNAL_SERVER_ERROR, e); - } - } - - /** - * Returns the version information of this REST resource. - * - *

    - * Subclasses can override this method to provide their own version information. - * - *

    - * The default implementation returns the value from the following locations (whichever matches first): - *

      - *
    1. {@link ResourceSwagger#externalDocs() @ResourceSwagger.externalDocs()} annotation on this class, and then any parent classes. - *
      Examples:
      - *

      - * // Direct value - * @RestResource( - * swagger=@ResourceSwagger(externalDocs="{url:'http://juneau.apache.org'}") - * ) - * public class MyResource {...} - * - * // Pulled from some other location - * @RestResource( - * swagger=@ResourceSwagger(externalDocs="$C{MyStrings/MyClass.myExternalDocs}") - * ) - * public class MyResource {...} - *

      - *
    2. Localized strings from resource bundle identified by {@link RestResource#messages() @RestResource.messages()} - * on the resource class, then any parent classes. - *
        - *
      1. [ClassName].externalDocs - *
      2. externalDocs - *
      - *
      Value is a JSON objec representation of a {@link ExternalDocumentation} object. - *
      Value can contain any SVL variables defined on the {@link ResourceSwagger#externalDocs() @ResourceSwagger.externalDocs()} annotation. - *
      Examples:
      - *

      - * // Direct value - * MyClass.externalDocs = {url:"http://juneau.apache.org"} - * - * // Pulled from some other location - * MyClass.externalDocs = $C{MyStrings/MyClass.myExternalDocs} - *

      - *
    3. externalDocs entry in swagger file. - *
    - * - * @param req The current request. - * @return - * The localized external documentation of this REST resource, or null if none was found. - * @throws Exception - */ - public ExternalDocumentation getExternalDocs(RestRequest req) throws Exception { - VarResolverSession vr = req.getVarResolverSession(); - JsonParser jp = JsonParser.DEFAULT; - try { - if (externalDocs != null) - return jp.parse(vr.resolve(externalDocs), ExternalDocumentation.class); - String externalDocs = context.getMessages().findFirstString(req.getLocale(), "externalDocs"); - if (externalDocs != null) - return jp.parse(vr.resolve(externalDocs), ExternalDocumentation.class); - Swagger s = getSwaggerFromFile(req); - if (s != null) - return s.getExternalDocs(); - return null; - } catch (Exception e) { - throw new RestException(SC_INTERNAL_SERVER_ERROR, e); - } - } - - private Operation getSwaggerOperationFromFile(Method method, RestRequest req) throws Exception { + private Operation getSwaggerOperation(Method method, RestRequest req) throws Exception { - Swagger s = getSwaggerFromFile(req); + Swagger s = getSwagger(req); if (s != null) { Map> sp = s.getPaths(); if (sp != null) { diff --git a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/RestRequest.java b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/RestRequest.java index e6c1aaa..d483bfa 100644 --- a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/RestRequest.java +++ b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/RestRequest.java @@ -1251,7 +1251,7 @@ public final class RestRequest extends HttpServletRequestWrapper { * * @param name The name of the resource (i.e. the value normally passed to {@link Class#getResourceAsStream(String)}. * @param resolveVars - * If true, any {@link org.apache.juneau.rest.annotation.Parameter @Parameter} variables will be + * If true, any SVL variables will be * resolved by the variable resolver returned by {@link #getVarResolverSession()}. *
    See {@link RestContext#getVarResolver()} for the list of supported variables. * @param mediaType The value to set as the "Content-Type" header for this object. @@ -1274,7 +1274,7 @@ public final class RestRequest extends HttpServletRequestWrapper { * * @param name The name of the resource (i.e. the value normally passed to {@link Class#getResourceAsStream(String)}. * @param resolveVars - * If true, any {@link org.apache.juneau.rest.annotation.Parameter @Parameter} variables will be + * If true, any SVL variables will be * resolved by the variable resolver returned by {@link #getVarResolverSession()}. *
    See {@link RestContext#getVarResolver()} for the list of supported variables. * @return A new reader resource, or null if resource could not be found. diff --git a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/MethodSwagger.java b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/MethodSwagger.java deleted file mode 100644 index b1169d5..0000000 --- a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/MethodSwagger.java +++ /dev/null @@ -1,210 +0,0 @@ -// *************************************************************************************************************************** -// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file * -// * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file * -// * to you 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 * -// * * -// * http://www.apache.org/licenses/LICENSE-2.0 * -// * * -// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an * -// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the * -// * specific language governing permissions and limitations under the License. * -// *************************************************************************************************************************** -package org.apache.juneau.rest.annotation; - -import org.apache.juneau.rest.*; - -/** - * Extended annotation for {@link RestMethod#swagger() RestMethod.swagger()}. - * - *
    See Also:
    - * - */ -public @interface MethodSwagger { - - /** - * Optional deprecated flag for the exposed API. - * - *

    - * Used to populate the Swagger deprecated field. - * - *

    Example:
    - *

    - * @RestMethod( - * swagger=@MethodSwagger( - * deprecated=true - * ) - * ) - *

    - * - *
    Notes:
    - *
      - *
    • - * Corresponds to the swagger field /paths/{path}/{method}/deprecated. - *
    - * - *
    See Also:
    - *
      - *
    • {@link BasicRestInfoProvider#isDeprecated(java.lang.reflect.Method, RestRequest) BasicRestInfoProvider.isDeprecated(Method,RestRequest)} - *
    - */ - boolean deprecated() default false; - - /** - * Optional external documentation information for the exposed API. - * - *

    - * Used to populate the Swagger external documentation field. - * - *

    - * A simplified JSON string with the following fields: - *

    - * { - * description: string, - * url: string - * } - *

    - * - *
    Example:
    - *

    - * @RestMethod( - * swagger=@MethodSwagger( - * "{url:'http://juneau.apache.org'}" - * ) - * ) - *

    - * - *
    Notes:
    - * - * - *
    See Also:
    - *
      - *
    • {@link BasicRestInfoProvider#getMethodExternalDocs(java.lang.reflect.Method, RestRequest) BasicRestInfoProvider.getMethodExternalDocs(Method,RestRequest)} - *
    - */ - String externalDocs() default ""; - - /** - * Optional parameter descriptions. - * - *

    - * This annotation is provided for documentation purposes and is used to populate the method "parameters" - * column on the Swagger page. - * - *

    Example:
    - *

    - * @RestMethod( - * name=POST, path="/{a}", - * description="This is my method.", - * swagger=@MethodSwagger( - * parameters={ - * @Parameter(in="path", name="a", description="The 'a' attribute"), - * @Parameter(in="query", name="b", description="The 'b' parameter", required=true), - * @Parameter(in="body", description="The HTTP content"), - * @Parameter(in="header", name="D", description="The 'D' header"), - * } - * ) - * ) - *

    - * - *
    Notes:
    - * - * - *
    See Also:
    - *
      - *
    • {@link BasicRestInfoProvider#getMethodParameters(java.lang.reflect.Method, RestRequest) BasicRestInfoProvider.getMethodParameters(Method,RestRequest)} - *
    - */ - Parameter[] parameters() default {}; - - /** - * Optional output description. - * - *

    - * This annotation is provided for documentation purposes and is used to populate the method "responses" - * column on the Swagger page. - * - *

    Example:
    - *

    - * @RestMethod( - * name=GET, path="/", - * swagger=@MethodSwagger( - * responses={ - * @Response(200), - * @Response( - * value=302, - * description="Thing wasn't found here", - * headers={ - * @Parameter(name="Location", description="The place to find the thing") - * } - * ) - * } - * ) - * ) - *

    - * - *
    Notes:
    - * - * - *
    See Also:
    - *
      - *
    • {@link BasicRestInfoProvider#getMethodResponses(java.lang.reflect.Method, RestRequest) BasicRestInfoProvider.getMethodResponses(Method,RestRequest)} - *
    - */ - Response[] responses() default {}; - - /** - * Optional tagging information for the exposed API. - * - *

    - * Used to populate the Swagger tags field. - * - *

    - * A comma-delimited list of tags for API documentation control. - *
    Tags can be used for logical grouping of operations by resources or any other qualifier. - * - *

    Example:
    - *

    - * @RestMethod( - * swagger=@MethodSwagger( - * tags="foo,bar" - * ) - * ) - *

    - * - *
    Notes:
    - * - * - *
    See Also:
    - *
      - *
    • {@link BasicRestInfoProvider#getMethodTags(java.lang.reflect.Method, RestRequest) BasicRestInfoProvider.getMethodTags(Method,RestRequest)} - *
    - */ - String tags() default ""; -} diff --git a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Parameter.java b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Parameter.java deleted file mode 100644 index 0ba0e07..0000000 --- a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Parameter.java +++ /dev/null @@ -1,213 +0,0 @@ -// *************************************************************************************************************************** -// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file * -// * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file * -// * to you 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 * -// * * -// * http://www.apache.org/licenses/LICENSE-2.0 * -// * * -// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an * -// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the * -// * specific language governing permissions and limitations under the License. * -// *************************************************************************************************************************** -package org.apache.juneau.rest.annotation; - -import static java.lang.annotation.ElementType.*; -import static java.lang.annotation.RetentionPolicy.*; - -import java.lang.annotation.*; - -/** - * Annotation used in conjunction with {@link MethodSwagger#parameters() @MethodSwagger.parameters()} to identify - * content and header descriptions on specific method requests. - * - *
    Example:
    - *

    - * @RestMethod( - * name="*", - * swagger=@MethodSwagger( - * parameters={ - * @Parameter(in="header", name="Range", description="$L{ContentRange.description}") - * } - * ) - * ) - * public void doAnything(RestRequest req, RestResponse res, @Method String method) { - * ... - * } - *

    - * - *
    See Also:
    - * - */ -@Documented -@Target(PARAMETER) -@Retention(RUNTIME) -@Inherited -public @interface Parameter { - - /** - * Declares the value of the parameter that the server will use if none is provided. - * - *

    - * For example a "count" to control the number of results per page might default to 100 if not supplied by the - * client in the request. - * (Note: "default" has no meaning for required parameters.) - * See - * http://json-schema.org/latest/json-schema-validation.html#anchor101. - * Unlike JSON Schema this value MUST conform to the defined type for this parameter. - */ - String _default() default ""; - - /** - * Sets the ability to pass empty-valued parameters. - * - *

    - * This is valid only for either query or formData parameters and allows you to send a - * parameter with a name only or an empty value. - * Default value is false. - */ - boolean allowEmptyValue() default false; - - /** - * Determines the format of the array if type array is used. - * - *

    - * Possible values are: - *

      - *
    • "csv" - comma separated values "foo,bar". - *
    • "ssv" - space separated values "foo bar". - *
    • "tsv" - tab separated values "foo\tbar". - *
    • "pipes" - pipe separated values "foo|bar". - *
    • "multi" - corresponds to multiple parameter instances instead of multiple values for a single - * instance "foo=bar&foo=baz". - * This is valid only for parameters in "query" or "formData". - *
    - * Default value is "csv". - */ - String collectionFormat() default ""; - - /** - * Parameter description (e.g. "Indicates the range returned when Range header is present in the request"). - * - *

    - * A brief description of the parameter. - * This could contain examples of use. - * GFM syntax can be used - * for rich text representation. - * - *

    - * The default value pulls the description from the description entry in the servlet resource bundle. - * (e.g. "myMethod.res.[code].[category].[name] = foo" or - * "MyServlet.myMethod.res.[code].[category].[name] = foo"). - */ - String description() default ""; - - /** - * The extending format for the previously mentioned type. - * - *

    - * See Data Type Formats for further - * details. - */ - String format() default ""; - - /** - * The location of the parameter. - * - *

    - * Possible values are: - *

      - *
    • "query" - *
    • "header" - *
    • "path" - *
    • "formData" - *
    • "body" - *
    - */ - String in() default ""; - - /** - * Required if type is "array". - * - *

    - * Describes the type of items in the array. - * - *

    Example:
    - *

    - * @RestMethod( - * parameters={ - * @Parameter( - * in="header", - * name="Foo", - * type="array", - * items="{type:'string',collectionFormat:'csv'}") - * } - * ) - * public void doAnything() { - *

    - * - *

    - * See Items Object for further details. - */ - String items() default ""; - - /** - * The name of the parameter (e.g. "Content-Range"). - * - *

    - * Parameter names are case sensitive. - * If in is "path", the name field MUST correspond to the associated path segment from the - * path field in the Paths Object. - * See Path Templating for further - * information. - * For all other cases, the name corresponds to the parameter name used based on the in property. - */ - String name() default ""; - - /** - * Determines whether this parameter is mandatory. - * - *

    - * If the parameter is in "path", this property is required and its value MUST be true. - * Otherwise, the property MAY be included and its default value is false. - */ - boolean required() default false; - - /** - * The schema defining the type used for the body parameter. - * - *

    - * Only applicable for in of type "body". - * - *

    - * The schema is a JSON object specified here. - * - *

    Example:
    - *

    - * @RestMethod( - * parameters={ - * @Parameter( - * in="header", - * name="Foo", - * schema="{format:'string',title:'Foo header',description:'Header that contains the Foo value.'}") - * } - * ) - * public void doAnything() { - *

    - */ - String schema() default ""; - - /** - * The type of the parameter. - * - *

    - * The value MUST be one of "string", "number", "integer", "boolean", - * "array" or "file". - * If type is "file", the consumes MUST be either "multipart/form-data", - * "application/x-www-form-urlencoded" or both and the parameter MUST be in "formData". - */ - String type() default "string"; -} diff --git a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/ResourceSwagger.java b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/ResourceSwagger.java deleted file mode 100644 index 31b5624..0000000 --- a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/ResourceSwagger.java +++ /dev/null @@ -1,333 +0,0 @@ -// *************************************************************************************************************************** -// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file * -// * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file * -// * to you 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 * -// * * -// * http://www.apache.org/licenses/LICENSE-2.0 * -// * * -// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an * -// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the * -// * specific language governing permissions and limitations under the License. * -// *************************************************************************************************************************** -package org.apache.juneau.rest.annotation; - -import org.apache.juneau.config.vars.*; -import org.apache.juneau.rest.vars.*; -import org.apache.juneau.svl.vars.*; - -/** - * Extended annotation for {@link RestResource#swagger() @RestResource.swagger()}. - * - *

    See Also:
    - * - */ -public @interface ResourceSwagger { - - /** - * Optional contact information for the exposed API. - * - *

    - * It is used to populate the Swagger contact field and to display on HTML pages. - * - *

    - * A simplified JSON string with the following fields: - *

    - * { - * name: string, - * url: string, - * email: string - * } - *

    - * - *

    - * The default value pulls the description from the contact entry in the servlet resource bundle. - * (e.g. "contact = {name:'John Smith',email:'john.smith@foo.bar'}" or - * "MyServlet.contact = {name:'John Smith',email:'john.smith@foo.bar'}"). - * - *

    Example:
    - *

    - * @RestResource( - * swagger=@MethodSwagger( - * contact="{name:'John Smith',email:'john.smith@foo.bar'}" - * ) - * ) - *

    - * - *

    - * Value can contain any of the following variables: - * {@link ConfigVar $C} - * {@link CoalesceVar $CO} - * {@link EnvVariablesVar $E} - * {@link FileVar $F} - * {@link ServletInitParamVar $I}, - * {@link IfVar $IF} - * {@link LocalizationVar $L} - * {@link RequestAttributeVar $RA} - * {@link RequestFormDataVar $RF} - * {@link RequestHeaderVar $RH} - * {@link RequestPathVar $RP} - * {@link RequestQueryVar $RQ} - * {@link RequestVar $R} - * {@link SystemPropertiesVar $S} - * {@link SerializedRequestAttrVar $SA} - * {@link SwitchVar $SW} - * {@link UrlVar $U} - * {@link UrlEncodeVar $UE} - * {@link WidgetVar $W} - * - *

    - * Corresponds to the swagger field /info/contact. - */ - String contact() default ""; - - /** - * Optional external documentation information for the exposed API. - * - *

    - * It is used to populate the Swagger external documentation field and to display on HTML pages. - * - *

    - * A simplified JSON string with the following fields: - *

    - * { - * description: string, - * url: string - * } - *

    - * - *

    - * The default value pulls the description from the externalDocs entry in the servlet resource bundle. - * (e.g. "externalDocs = {url:'http://juneau.apache.org'}" or - * "MyServlet.externalDocs = {url:'http://juneau.apache.org'}"). - * - *

    Example:
    - *

    - * @RestResource( - * swagger=@MethodSwagger( - * externalDocs="{url:'http://juneau.apache.org'}" - * ) - * ) - *

    - * - *

    - * Value can contain any of the following variables: - * {@link ConfigVar $C} - * {@link CoalesceVar $CO} - * {@link EnvVariablesVar $E} - * {@link FileVar $F} - * {@link ServletInitParamVar $I}, - * {@link IfVar $IF} - * {@link LocalizationVar $L} - * {@link RequestAttributeVar $RA} - * {@link RequestFormDataVar $RF} - * {@link RequestHeaderVar $RH} - * {@link RequestPathVar $RP} - * {@link RequestQueryVar $RQ} - * {@link RequestVar $R} - * {@link SystemPropertiesVar $S} - * {@link SerializedRequestAttrVar $SA} - * {@link SwitchVar $SW} - * {@link UrlVar $U} - * {@link UrlEncodeVar $UE} - * {@link WidgetVar $W} - * - *

    - * Corresponds to the swagger field /tags. - */ - String externalDocs() default ""; - - /** - * Optional license information for the exposed API. - * - *

    - * It is used to populate the Swagger license field and to display on HTML pages. - * - *

    - * A simplified JSON string with the following fields: - *

    - * { - * name: string, - * url: string - * } - *

    - * - *

    - * The default value pulls the description from the license entry in the servlet resource bundle. - * (e.g. "license = {name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'}" or - * "MyServlet.license = {name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'}"). - * - *

    Example:
    - *

    - * @RestResource( - * swagger=@MethodSwagger( - * license="{name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'}" - * ) - * ) - *

    - * - *

    - * Value can contain any of the following variables: - * {@link ConfigVar $C} - * {@link CoalesceVar $CO} - * {@link EnvVariablesVar $E} - * {@link FileVar $F} - * {@link ServletInitParamVar $I}, - * {@link IfVar $IF} - * {@link LocalizationVar $L} - * {@link RequestAttributeVar $RA} - * {@link RequestFormDataVar $RF} - * {@link RequestHeaderVar $RH} - * {@link RequestPathVar $RP} - * {@link RequestQueryVar $RQ} - * {@link RequestVar $R} - * {@link SystemPropertiesVar $S} - * {@link SerializedRequestAttrVar $SA} - * {@link SwitchVar $SW} - * {@link UrlVar $U} - * {@link UrlEncodeVar $UE} - * {@link WidgetVar $W} - * - *

    - * Corresponds to the swagger field /info/license. - */ - String license() default ""; - - /** - * Optional tagging information for the exposed API. - * - *

    - * It is used to populate the Swagger tags field and to display on HTML pages. - * - *

    - * A simplified JSON string with the following fields: - *

    - * [ - * { - * name: string, - * description: string, - * externalDocs: { - * description: string, - * url: string - * } - * } - * ] - *

    - * - *

    - * The default value pulls the description from the tags entry in the servlet resource bundle. - * (e.g. "tags = [{name:'Foo',description:'Foobar'}]" or - * "MyServlet.tags = [{name:'Foo',description:'Foobar'}]"). - * - *

    Example:
    - *

    - * @RestResource( - * swagger=@MethodSwagger( - * tags="[{name:'Foo',description:'Foobar'}]" - * ) - * ) - *

    - * - *

    - * Value can contain any of the following variables: - * {@link ConfigVar $C} - * {@link CoalesceVar $CO} - * {@link EnvVariablesVar $E} - * {@link FileVar $F} - * {@link ServletInitParamVar $I}, - * {@link IfVar $IF} - * {@link LocalizationVar $L} - * {@link RequestAttributeVar $RA} - * {@link RequestFormDataVar $RF} - * {@link RequestHeaderVar $RH} - * {@link RequestPathVar $RP} - * {@link RequestQueryVar $RQ} - * {@link RequestVar $R} - * {@link SystemPropertiesVar $S} - * {@link SerializedRequestAttrVar $SA} - * {@link SwitchVar $SW} - * {@link UrlVar $U} - * {@link UrlEncodeVar $UE} - * {@link WidgetVar $W} - * - *

    - * Corresponds to the swagger field /tags. - */ - String tags() default ""; - - /** - * Optional servlet terms-of-service for this API. - * - *

    - * It is used to populate the Swagger terms-of-service field. - * - *

    - * The default value pulls the description from the termsOfService entry in the servlet resource bundle. - * (e.g. "termsOfService = foo" or "MyServlet.termsOfService = foo"). - * - *

    - * Value can contain any of the following variables: - * {@link ConfigVar $C} - * {@link CoalesceVar $CO} - * {@link EnvVariablesVar $E} - * {@link FileVar $F} - * {@link ServletInitParamVar $I}, - * {@link IfVar $IF} - * {@link LocalizationVar $L} - * {@link RequestAttributeVar $RA} - * {@link RequestFormDataVar $RF} - * {@link RequestHeaderVar $RH} - * {@link RequestPathVar $RP} - * {@link RequestQueryVar $RQ} - * {@link RequestVar $R} - * {@link SystemPropertiesVar $S} - * {@link SerializedRequestAttrVar $SA} - * {@link SwitchVar $SW} - * {@link UrlVar $U} - * {@link UrlEncodeVar $UE} - * {@link WidgetVar $W} - * - *

    - * Corresponds to the swagger field /info/termsOfService. - */ - String termsOfService() default ""; - - /** - * Provides the version of the application API (not to be confused with the specification version). - * - *

    - * It is used to populate the Swagger version field and to display on HTML pages. - * - *

    - * The default value pulls the description from the version entry in the servlet resource bundle. - * (e.g. "version = 2.0" or "MyServlet.version = 2.0"). - * - *

    - * Value can contain any of the following variables: - * {@link ConfigVar $C} - * {@link CoalesceVar $CO} - * {@link EnvVariablesVar $E} - * {@link FileVar $F} - * {@link ServletInitParamVar $I}, - * {@link IfVar $IF} - * {@link LocalizationVar $L} - * {@link RequestAttributeVar $RA} - * {@link RequestFormDataVar $RF} - * {@link RequestHeaderVar $RH} - * {@link RequestPathVar $RP} - * {@link RequestQueryVar $RQ} - * {@link RequestVar $R} - * {@link SystemPropertiesVar $S} - * {@link SerializedRequestAttrVar $SA} - * {@link SwitchVar $SW} - * {@link UrlVar $U} - * {@link UrlEncodeVar $UE} - * {@link WidgetVar $W} - * - *

    - * Corresponds to the swagger field /info/version. - */ - String version() default ""; -} diff --git a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Response.java b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Response.java deleted file mode 100644 index 6aab540..0000000 --- a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Response.java +++ /dev/null @@ -1,107 +0,0 @@ -// *************************************************************************************************************************** -// * Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file * -// * distributed with this work for additional information regarding copyright ownership. The ASF licenses this file * -// * to you 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 * -// * * -// * http://www.apache.org/licenses/LICENSE-2.0 * -// * * -// * Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an * -// * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the * -// * specific language governing permissions and limitations under the License. * -// *************************************************************************************************************************** -package org.apache.juneau.rest.annotation; - -import static java.lang.annotation.ElementType.*; -import static java.lang.annotation.RetentionPolicy.*; - -import java.lang.annotation.*; - -import org.apache.juneau.rest.*; - -/** - * Annotation used in conjunction with {@link MethodSwagger#responses() @MethodSwagger.responses()} to identify possible responses by the method. - * - *

    Example:
    - *

    - * @RestMethod( - * name="*", - * swagger=@ResourceSwagger( - * responses={ - * @Response(value=200,description="Everything was great."), - * @Response(value=404,description="File was not found.") - * @Response(500), - * } - * ) - * ) - * public void doAnything(RestRequest req, RestResponse res, @Method String method) { - * ... - * } - *

    - * - *
    See Also:
    - * - */ -@Documented -@Target(PARAMETER) -@Retention(RUNTIME) -@Inherited -public @interface Response { - - /** - * Optional description. - * - *

    - * The default value pulls the description from the description entry in the servlet resource bundle. - * (e.g. "myMethod.res.[code].description = foo" or - * "MyServlet.myMethod.res.[code].description = foo"). - * - *

    - * This field can contain variables (e.g. "$L{my.localized.variable}"). - *
    See {@link RestContext#getVarResolver()} for the list of supported variables. - * - *

    - * Corresponds to the swagger field /paths/{path}/{method}/responses/{code}/description. - */ - String description() default ""; - - /** - * Optional response headers. - * - *

    - * Response variables can also be defined in the servlet resource bundle. - * (e.g. "myMethod.res.[code].[category].[name] = foo" or - * "MyServlet.myMethod.res.[code].[category].[name] = foo"). - */ - Parameter[] headers() default {}; - - /** - * A definition of the response structure. - * - *

    - * It can be a primitive, an array or an object. - * If this field does not exist, it means no content is returned as part of the response. - * As an extension to the Schema Object, - * its root type value may also be "file". - * This SHOULD be accompanied by a relevant produces mime-type. - * - *

    Example:
    - *

    - * @RestMethod( - * name="*", - * swagger=@MethodSwagger( - * responses={ - * @Response(value=200,schema="{type:'string',description:'A serialized Person bean.'}"), - * } - * ) - *

    - */ - String schema() default ""; - - /** - * HTTP response code. - */ - int value(); -} diff --git a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/RestMethod.java b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/RestMethod.java index bef4796..1461deb 100644 --- a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/RestMethod.java +++ b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/RestMethod.java @@ -737,7 +737,40 @@ public @interface RestMethod { String[] consumes() default {}; /** + /** * Provides swagger-specific metadata on this method. + * + *

    + * Used to populate the auto-generated OPTIONS swagger documentation. + * + *

    + * The format of this annotation is JSON when all individual parts are concatenated. + *
    The starting and ending '{'/'}' characters around the entire value are optional. + * + *

    Example:
    + *

    + * @RestMethod( + * name=PUT, + * path="/{propertyName}", + * + * // Swagger info. + * swagger={ + * "parameters:[", + * "{name:'propertyName',in:'path',description:'The system property name.'},", + * "{in:'body',description:'The new system property value.'}", + * "],", + * "responses:{", + * "302: {headers:{Location:{description:'The root URL of this resource.'}}},", + * "403: {description:'User is not an admin.'}", + * "}" + * } + * ) + *

    + * + *
    See Also:
    + *
      + *
    • {@link RestInfoProvider#getSwagger(RestRequest)} + *
    */ - MethodSwagger swagger() default @MethodSwagger; + String[] swagger() default {}; } diff --git a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/RestResource.java b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/RestResource.java index 37973e6..f85a549 100644 --- a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/RestResource.java +++ b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/RestResource.java @@ -839,20 +839,24 @@ public @interface RestResource { *

    * Used to populate the auto-generated OPTIONS swagger documentation. * + *

    + * The format of this annotation is JSON when all individual parts are concatenated. + *
    The starting and ending '{'/'}' characters around the entire value are optional. + * *

    Example:
    *

    * @RestResource( * path="/addressBook", * * // Swagger info. - * swagger=@ResourceSwagger( - * contact="{name:'John Smith',email:'john@smith.com'}", - * license="{name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'}", - * version="2.0", - * termsOfService="You're on your own.", - * tags="[{name:'Java',description:'Java utility',externalDocs:{description:'Home page',url:'http://juneau.apache.org'}}]", - * externalDocs="{description:'Home page',url:'http://juneau.apache.org'}" - * ) + * swagger={ + * "contact:{name:'John Smith',email:'john@smith.com'},", + * "license:{name:'Apache 2.0',url:'http://www.apache.org/licenses/LICENSE-2.0.html'},", + * "version:'2.0',, + * "termsOfService:'You are on your own.',", + * "tags:[{name:'Java',description:'Java utility',externalDocs:{description:'Home page',url:'http://juneau.apache.org'}}],", + * "externalDocs:{description:'Home page',url:'http://juneau.apache.org'}" + * } * ) *

    * @@ -861,7 +865,7 @@ public @interface RestResource { *
  • {@link RestInfoProvider#getSwagger(RestRequest)} *
*/ - ResourceSwagger swagger() default @ResourceSwagger; + String[] swagger() default {}; /** * Optional servlet title. -- To stop receiving notification emails like this one, please contact jamesbognar@apache.org.