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 6720122 Swagger enhancements. 6720122 is described below commit 6720122e93eb768de16e3b44b63fb32a0e6955fa Author: JamesBognar <jamesbog...@apache.org> AuthorDate: Sun Apr 29 20:37:36 2018 -0400 Swagger enhancements. --- .../org/apache/juneau/rest/annotation/Body.java | 16 +++++ .../juneau/rest/annotation/MethodSwagger.java | 67 ++++++--------------- .../juneau/rest/annotation/ResourceSwagger.java | 9 +++ .../apache/juneau/rest/annotation/Response.java | 18 ++++++ .../juneau/rest/annotation/ResponseStatuses.java | 12 +++- .../juneau/rest/BasicRestInfoProviderTest.java | 70 +++++++++++++++++++++- 6 files changed, 141 insertions(+), 51 deletions(-) diff --git a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Body.java b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Body.java index 6fcc1a4..9013981 100644 --- a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Body.java +++ b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/Body.java @@ -403,5 +403,21 @@ public @interface Body { */ String[] example() default {}; + /** + * Defines the swagger value <code>/paths/{path}/{method}/parameters/#/x-examples</code>. + * + * <p> + * This is a JSON object whose keys are media types and values are string representations of that value. + * + * <h5 class='section'>Notes:</h5> + * <ul class='spaced-list'> + * <li> + * The format of the value is a JSON object. + * <br>Multiple lines are concatenated with newlines. + * <li> + * Supports <a class="doclink" href="../../../../../overview-summary.html#DefaultRestSvlVariables">initialization-time and request-time variables</a> + * (e.g. <js>"$L{my.localized.variable}"</js>). + * </ul> + */ String[] examples() default {}; } 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 index 10efb2f..0878962 100644 --- 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 @@ -28,64 +28,27 @@ public @interface MethodSwagger { * * <p> * Used for free-form Swagger documentation of a REST resource. - * - * - swagger={ - "tags:[ 'store' ],", - "responses:{", - "200:{ 'x-example':{AVAILABLE:123} }", - "},", - "security:[ { api_key:[] } ]" - } - ) - swagger={ - "tags:[ 'store' ],", - "responses:{", - "200:{ 'x-example':{AVAILABLE:123} }", - "},", - "security:[ { api_key:[] } ]" - } - 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'}}}", - "}" - } - swagger=@MethodSwagger( - 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'}}}", - } - ) - * - * */ String[] value() default {}; + /** + * {@link TODO} + */ String[] summary() default {}; + /** + * {@link TODO} + */ String[] description() default {}; + /** + * {@link TODO} + */ String operationId() default ""; + /** + * {@link TODO} + */ String[] schemes() default {}; /** @@ -111,8 +74,14 @@ public @interface MethodSwagger { */ String deprecated() default ""; + /** + * {@link TODO} + */ String[] consumes() default {}; + /** + * {@link TODO} + */ String[] produces() default {}; /** 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 index c13cdac..e9cf58d 100644 --- 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 @@ -26,10 +26,19 @@ import org.apache.juneau.svl.vars.*; */ public @interface ResourceSwagger { + /** + * {@link TODO} + */ String[] value() default {}; + /** + * {@link TODO} + */ String[] title() default {}; + /** + * {@link TODO} + */ String[] description() 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 index cc17898..e39b9b2 100644 --- 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 @@ -202,5 +202,23 @@ public @interface Response { */ String[] example() default {}; + /** + * Used for populating the Swagger field <code>/paths/{path}/{method}/responses/{status-code}/examples</code>. + * + * <p> + * The format is a JSON object with keys as media types and values as string representations of the body response. + * + * <h5 class='section'>Notes:</h5> + * <ul class='spaced-list'> + * <li> + * The format of the value is a JSON object. + * <br>Multiple lines are concatenated with newlines. + * <li> + * The leading/trailing <code>{ }</code> characters are optional. + * <li> + * Supports <a class="doclink" href="../../../../../overview-summary.html#DefaultRestSvlVariables">initialization-time and request-time variables</a> + * (e.g. <js>"$L{my.localized.variable}"</js>). + * </ul> + */ String[] examples() default {}; } diff --git a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/ResponseStatuses.java b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/ResponseStatuses.java index d5bbee4..1111aeb 100644 --- a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/ResponseStatuses.java +++ b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/annotation/ResponseStatuses.java @@ -17,11 +17,21 @@ import static java.lang.annotation.RetentionPolicy.*; import java.lang.annotation.*; +/** + * Used to associate multiple {@link ResponseStatus @ResponseStatus} annotations to the same parameter or class. + * + * <p> + * Since Juneau currently prereq's Java 1.7, we cannot take advantage of annotation duplication support in Java 8. + * <br>This annotation overcomes that limitation. + */ @Documented -@Target({TYPE}) +@Target({PARAMETER,TYPE}) @Retention(RUNTIME) @Inherited public @interface ResponseStatuses { + /** + * Specifies one or more {@link ResponseStatus @ResponseStatus} annotations to apply to the same parameter or class. + */ ResponseStatus[] value() default {}; } \ No newline at end of file diff --git a/juneau-rest/juneau-rest-server/src/test/java/org/apache/juneau/rest/BasicRestInfoProviderTest.java b/juneau-rest/juneau-rest-server/src/test/java/org/apache/juneau/rest/BasicRestInfoProviderTest.java index d8f2780..26962ae 100644 --- a/juneau-rest/juneau-rest-server/src/test/java/org/apache/juneau/rest/BasicRestInfoProviderTest.java +++ b/juneau-rest/juneau-rest-server/src/test/java/org/apache/juneau/rest/BasicRestInfoProviderTest.java @@ -3371,9 +3371,77 @@ public class BasicRestInfoProviderTest { // /paths/<path>/<method>/responses/<response>/schema //----------------------------------------------------------------------------------------------------------------- - // TODO + //----------------------------------------------------------------------------------------------------------------- + // @Header on POJO + //----------------------------------------------------------------------------------------------------------------- + + //----------------------------------------------------------------------------------------------------------------- + // @Header on parameter + //----------------------------------------------------------------------------------------------------------------- + + //----------------------------------------------------------------------------------------------------------------- + // @Query on POJO + //----------------------------------------------------------------------------------------------------------------- + + //----------------------------------------------------------------------------------------------------------------- + // @Query on parameter + //----------------------------------------------------------------------------------------------------------------- + + //----------------------------------------------------------------------------------------------------------------- + // @FormData on POJO + //----------------------------------------------------------------------------------------------------------------- + + //----------------------------------------------------------------------------------------------------------------- + // @FormData on parameter + //----------------------------------------------------------------------------------------------------------------- + + //----------------------------------------------------------------------------------------------------------------- + // @Path on POJO + //----------------------------------------------------------------------------------------------------------------- + + //----------------------------------------------------------------------------------------------------------------- + // @Path on parameter + //----------------------------------------------------------------------------------------------------------------- + + //----------------------------------------------------------------------------------------------------------------- + // @Body on POJO + //----------------------------------------------------------------------------------------------------------------- + + //----------------------------------------------------------------------------------------------------------------- + // @Body on parameter + //----------------------------------------------------------------------------------------------------------------- + + //----------------------------------------------------------------------------------------------------------------- + // @Response on POJO + //----------------------------------------------------------------------------------------------------------------- + + //----------------------------------------------------------------------------------------------------------------- + // @Response on parameter + //----------------------------------------------------------------------------------------------------------------- + + //----------------------------------------------------------------------------------------------------------------- + // @Response on throwable + //----------------------------------------------------------------------------------------------------------------- + + //----------------------------------------------------------------------------------------------------------------- + // @Responses on POJO + //----------------------------------------------------------------------------------------------------------------- + //----------------------------------------------------------------------------------------------------------------- + // @ResponseStatus on POJO + //----------------------------------------------------------------------------------------------------------------- + + //----------------------------------------------------------------------------------------------------------------- + // @ResponseStatuses on POJO + //----------------------------------------------------------------------------------------------------------------- + //----------------------------------------------------------------------------------------------------------------- + // @ResponseHeader on POJO + //----------------------------------------------------------------------------------------------------------------- + + //----------------------------------------------------------------------------------------------------------------- + // @ResponseHeaders on POJO + //----------------------------------------------------------------------------------------------------------------- @Bean(typeName="Foo") public static class Foo { -- To stop receiving notification emails like this one, please contact jamesbog...@apache.org.