You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@juneau.apache.org by ja...@apache.org on 2017/09/02 14:10:27 UTC
[05/51] [partial] incubator-juneau git commit: Add project
hierarchies, part 1
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/75b0d8ee/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/SecurityScheme.java
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/SecurityScheme.java b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/SecurityScheme.java
new file mode 100644
index 0000000..547ac3c
--- /dev/null
+++ b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/SecurityScheme.java
@@ -0,0 +1,428 @@
+// ***************************************************************************************************************************
+// * 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.dto.swagger;
+
+import static org.apache.juneau.internal.ArrayUtils.*;
+
+import java.util.*;
+
+import org.apache.juneau.*;
+import org.apache.juneau.annotation.*;
+
+/**
+ * Allows the definition of a security scheme that can be used by the operations.
+ *
+ * <p>
+ * Supported schemes are basic authentication, an API key (either as a header or as a query parameter) and OAuth2's
+ * common flows (implicit, password, application and access code).
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * <jc>// Basic authentication sample</jc>
+ * {
+ * <js>"type"</js>: <js>"basic"</js>
+ * }
+ *
+ * <jc>// API key sample</jc>
+ * {
+ * <js>"type"</js>: <js>"apiKey"</js>,
+ * <js>"name"</js>: <js>"api_key"</js>,
+ * <js>"in"</js>: <js>"header"</js>
+ * }
+ *
+ * <jc>// Implicit OAuth2 sample</jc>
+ * {
+ * <js>"type"</js>: <js>"oauth2"</js>,
+ * <js>"authorizationUrl"</js>: <js>"http://swagger.io/api/oauth/dialog"</js>,
+ * <js>"flow"</js>: <js>"implicit"</js>,
+ * <js>"scopes"</js>: {
+ * <js>"write:pets"</js>: <js>"modify pets in your account"</js>,
+ * <js>"read:pets"</js>: <js>"read your pets"</js>
+ * }
+ * }
+ * </p>
+ *
+ * <h6 class='topic'>Additional Information</h6>
+ * <ul class='doctree'>
+ * <li class='link'>
+ * <a class='doclink' href='../../../../../overview-summary.html#DTOs'>Juneau Data Transfer Objects
+ * (org.apache.juneau.dto)</a>
+ * <ul>
+ * <li class='sublink'>
+ * <a class='doclink' href='../../../../../overview-summary.html#DTOs.Swagger'>Swagger</a>
+ * </ul>
+ * </li>
+ * <li class='jp'>
+ * <a class='doclink' href='package-summary.html#TOC'>org.apache.juneau.dto.swagger</a>
+ * </li>
+ * </ul>
+ */
+@Bean(properties="type,description,name,in,flow,authorizationUrl,tokenUrl,scopes")
+@SuppressWarnings("hiding")
+public class SecurityScheme extends SwaggerElement {
+
+ private static final String[] VALID_TYPES = {"basic", "apiKey", "oauth2"};
+
+ private String type;
+ private String description;
+ private String name;
+ private String in;
+ private String flow;
+ private String authorizationUrl;
+ private String tokenUrl;
+ private Map<String,String> scopes;
+
+ @Override /* SwaggerElement */
+ protected SecurityScheme strict() {
+ super.strict();
+ return this;
+ }
+
+ /**
+ * Bean property getter: <property>type</property>.
+ *
+ * <p>
+ * Required. The type of the security scheme.
+ *
+ * <p>
+ * Valid values are <js>"basic"</js>, <js>"apiKey"</js> or <js>"oauth2"</js>.
+ *
+ * @return The value of the <property>type</property> property on this bean, or <jk>null</jk> if it is not set.
+ */
+ public String getType() {
+ return type;
+ }
+
+ /**
+ * Bean property setter: <property>type</property>.
+ *
+ * <p>
+ * Required. The type of the security scheme.
+ *
+ * <p>
+ * Valid values are <js>"basic"</js>, <js>"apiKey"</js> or <js>"oauth2"</js>.
+ *
+ * @param type The new value for the <property>type</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public SecurityScheme setType(String type) {
+ if (isStrict() && ! contains(type, VALID_TYPES))
+ throw new FormattedRuntimeException(
+ "Invalid value passed in to setType(String). Value=''{0}'', valid values={1}",
+ type, VALID_TYPES
+ );
+ this.type = type;
+ return this;
+ }
+
+ /**
+ * Synonym for {@link #setType(String)}.
+ *
+ * @param type The new value for the <property>type</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public SecurityScheme type(String type) {
+ return setType(type);
+ }
+
+ /**
+ * Bean property getter: <property>description</property>.
+ *
+ * <p>
+ * A short description for security scheme.
+ *
+ * @return
+ * The value of the <property>description</property> property on this bean, or <jk>null</jk> if it is not set.
+ */
+ public String getDescription() {
+ return description;
+ }
+
+ /**
+ * Bean property setter: <property>description</property>.
+ *
+ * <p>
+ * A short description for security scheme.
+ *
+ * @param description The new value for the <property>description</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public SecurityScheme setDescription(String description) {
+ this.description = description;
+ return this;
+ }
+
+ /**
+ * Synonym for {@link #setDescription(String)}.
+ *
+ * @param description The new value for the <property>description</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public SecurityScheme description(String description) {
+ return setDescription(description);
+ }
+
+ /**
+ * Bean property getter: <property>name</property>.
+ *
+ * <p>
+ * The name of the header or query parameter to be used.
+ *
+ * @return The value of the <property>name</property> property on this bean, or <jk>null</jk> if it is not set.
+ */
+ public String getName() {
+ return name;
+ }
+
+ /**
+ * Bean property setter: <property>name</property>.
+ *
+ * <p>
+ * The name of the header or query parameter to be used.
+ *
+ * @param name The new value for the <property>name</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public SecurityScheme setName(String name) {
+ this.name = name;
+ return this;
+ }
+
+ /**
+ * Synonym for {@link #setName(String)}.
+ *
+ * @param name The new value for the <property>name</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public SecurityScheme name(String name) {
+ return setName(name);
+ }
+
+ /**
+ * Bean property getter: <property>in</property>.
+ *
+ * <p>
+ * The location of the API key. Valid values are <js>"query"</js> or <js>"header"</js>.
+ *
+ * @return The value of the <property>in</property> property on this bean, or <jk>null</jk> if it is not set.
+ */
+ public String getIn() {
+ return in;
+ }
+
+ /**
+ * Bean property setter: <property>in</property>.
+ *
+ * <p>
+ * The location of the API key. Valid values are <js>"query"</js> or <js>"header"</js>.
+ *
+ * @param in The new value for the <property>in</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public SecurityScheme setIn(String in) {
+ this.in = in;
+ return this;
+ }
+
+ /**
+ * Synonym for {@link #setIn(String)}.
+ *
+ * @param in The new value for the <property>in</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public SecurityScheme in(String in) {
+ return setIn(in);
+ }
+
+ /**
+ * Bean property getter: <property>flow</property>.
+ *
+ * <p>
+ * The flow used by the OAuth2 security scheme.
+ *
+ * <p>
+ * Valid values are <js>"implicit"</js>, <js>"password"</js>, <js>"application"</js> or <js>"accessCode"</js>.
+ *
+ * @return The value of the <property>flow</property> property on this bean, or <jk>null</jk> if it is not set.
+ */
+ public String getFlow() {
+ return flow;
+ }
+
+ /**
+ * Bean property setter: <property>flow</property>.
+ *
+ * <p>
+ * The flow used by the OAuth2 security scheme.
+ *
+ * <p>
+ * Valid values are <js>"implicit"</js>, <js>"password"</js>, <js>"application"</js> or <js>"accessCode"</js>.
+ *
+ * @param flow The new value for the <property>flow</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public SecurityScheme setFlow(String flow) {
+ this.flow = flow;
+ return this;
+ }
+
+ /**
+ * Synonym for {@link #setFlow(String)}.
+ *
+ * @param flow The new value for the <property>flow</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public SecurityScheme flow(String flow) {
+ return setFlow(flow);
+ }
+
+ /**
+ * Bean property getter: <property>authorizationUrl</property>.
+ *
+ * <p>
+ * The authorization URL to be used for this flow.
+ *
+ * <p>
+ * This SHOULD be in the form of a URL.
+ *
+ * @return
+ * The value of the <property>authorizationUrl</property> property on this bean, or <jk>null</jk> if it
+ * is not set.
+ */
+ public String getAuthorizationUrl() {
+ return authorizationUrl;
+ }
+
+ /**
+ * Bean property setter: <property>authorizationUrl</property>.
+ *
+ * <p>
+ * The authorization URL to be used for this flow.
+ *
+ * <p>
+ * This SHOULD be in the form of a URL.
+ *
+ * @param authorizationUrl The new value for the <property>authorizationUrl</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public SecurityScheme setAuthorizationUrl(String authorizationUrl) {
+ this.authorizationUrl = authorizationUrl;
+ return this;
+ }
+
+ /**
+ * Synonym for {@link #setAuthorizationUrl(String)}.
+ *
+ * @param authorizationUrl The new value for the <property>authorizationUrl</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public SecurityScheme authorizationUrl(String authorizationUrl) {
+ return setAuthorizationUrl(authorizationUrl);
+ }
+
+ /**
+ * Bean property getter: <property>tokenUrl</property>.
+ *
+ * <p>
+ * The token URL to be used for this flow.
+ *
+ * <p>
+ * This SHOULD be in the form of a URL.
+ *
+ * @return The value of the <property>tokenUrl</property> property on this bean, or <jk>null</jk> if it is not set.
+ */
+ public String getTokenUrl() {
+ return tokenUrl;
+ }
+
+ /**
+ * Bean property setter: <property>tokenUrl</property>.
+ *
+ * <p>
+ * The token URL to be used for this flow.
+ *
+ * <p>
+ * This SHOULD be in the form of a URL.
+ *
+ * @param tokenUrl The new value for the <property>tokenUrl</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public SecurityScheme setTokenUrl(String tokenUrl) {
+ this.tokenUrl = tokenUrl;
+ return this;
+ }
+
+ /**
+ * Synonym for {@link #setTokenUrl(String)}.
+ *
+ * @param tokenUrl The new value for the <property>tokenUrl</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public SecurityScheme tokenUrl(String tokenUrl) {
+ return setTokenUrl(tokenUrl);
+ }
+
+ /**
+ * Bean property getter: <property>scopes</property>.
+ *
+ * <p>
+ * The available scopes for the OAuth2 security scheme.
+ *
+ * @return The value of the <property>scopes</property> property on this bean, or <jk>null</jk> if it is not set.
+ */
+ public Map<String,String> getScopes() {
+ return scopes;
+ }
+
+ /**
+ * Bean property setter: <property>scopes</property>.
+ *
+ * <p>
+ * The available scopes for the OAuth2 security scheme.
+ *
+ * @param scopes The new value for the <property>scopes</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public SecurityScheme setScopes(Map<String,String> scopes) {
+ this.scopes = scopes;
+ return this;
+ }
+
+ /**
+ * Bean property adder: <property>scopes</property>.
+ *
+ * <p>
+ * The available scopes for the OAuth2 security scheme.
+ *
+ * @param name The name of the scope.
+ * @param description A short description of the scope.
+ * @return This object (for method chaining).
+ */
+ public SecurityScheme addScope(String name, String description) {
+ if (scopes == null)
+ scopes = new TreeMap<String,String>();
+ scopes.put(name, description);
+ return this;
+ }
+
+ /**
+ * Synonym for {@link #addScope(String,String)}.
+ *
+ * @param name The name of the scope.
+ * @param description A short description of the scope.
+ * @return This object (for method chaining).
+ */
+ public SecurityScheme scope(String name, String description) {
+ return addScope(name, description);
+ }
+}
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/75b0d8ee/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/Swagger.java
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/Swagger.java b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/Swagger.java
new file mode 100644
index 0000000..8500444
--- /dev/null
+++ b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/Swagger.java
@@ -0,0 +1,1037 @@
+// ***************************************************************************************************************************
+// * 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.dto.swagger;
+
+import java.util.*;
+
+import org.apache.juneau.annotation.*;
+import org.apache.juneau.http.*;
+import org.apache.juneau.utils.*;
+
+/**
+ * This is the root document object for the API specification.
+ *
+ * <h6 class='topic'>Additional Information</h6>
+ * <ul class='doctree'>
+ * <li class='link'>
+ * <a class='doclink' href='../../../../../overview-summary.html#DTOs'>Juneau Data Transfer Objects
+ * (org.apache.juneau.dto)</a>
+ * <ul>
+ * <li class='sublink'>
+ * <a class='doclink' href='../../../../../overview-summary.html#DTOs.Swagger'>Swagger</a>
+ * </ul>
+ * </li>
+ * <li class='jp'>
+ * <a class='doclink' href='package-summary.html#TOC'>org.apache.juneau.dto.swagger</a>
+ * </li>
+ * </ul>
+ */
+@Bean(properties="swagger,info,tags,externalDocs,basePath,schemes,consumes,produces,paths,definitions,parameters,responses,securityDefinitions,security")
+@SuppressWarnings("hiding")
+public class Swagger extends SwaggerElement {
+
+ /** Represents a null swagger */
+ public static final Swagger NULL = new Swagger();
+
+ private String swagger = "2.0";
+ private Info info;
+ private String host, basePath;
+ private List<String> schemes;
+ private List<MediaType> consumes;
+ private List<MediaType> produces;
+ private Map<String,Map<String,Operation>> paths;
+ private Map<String,SchemaInfo> definitions;
+ private Map<String,ParameterInfo> parameters;
+ private Map<String,ResponseInfo> responses;
+ private Map<String,SecurityScheme> securityDefinitions;
+ private List<Map<String,List<String>>> security;
+ private List<Tag> tags;
+ private ExternalDocumentation externalDocs;
+
+ /**
+ * Bean property getter: <property>swagger</property>.
+ *
+ * <p>
+ * Required. Specifies the Swagger Specification version being used.
+ *
+ * <p>
+ * It can be used by the Swagger UI and other clients to interpret the API listing.
+ * The value MUST be <js>"2.0"</js>.
+ *
+ * @return The value of the <property>swagger</property> property on this bean, or <jk>null</jk> if it is not set.
+ */
+ public String getSwagger() {
+ return swagger;
+ }
+
+ /**
+ * Bean property setter: <property>swagger</property>.
+ *
+ * <p>
+ * Required. Specifies the Swagger Specification version being used.
+ *
+ * <p>
+ * It can be used by the Swagger UI and other clients to interpret the API listing.
+ * The value MUST be <js>"2.0"</js>.
+ *
+ * @param swagger The new value for the <property>swagger</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Swagger setSwagger(String swagger) {
+ this.swagger = swagger;
+ return this;
+ }
+
+ /**
+ * Synonym for {@link #setSwagger(String)}.
+ *
+ * @param swagger The new value for the <property>swagger</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Swagger swagger(String swagger) {
+ return setSwagger(swagger);
+ }
+
+ /**
+ * Bean property getter: <property>info</property>.
+ *
+ * <p>
+ * Required. Provides metadata about the API.
+ *
+ * <p>
+ * The metadata can be used by the clients if needed.
+ *
+ * @return The value of the <property>info</property> property on this bean, or <jk>null</jk> if it is not set.
+ */
+ public Info getInfo() {
+ return info;
+ }
+
+ /**
+ * Bean property setter: <property>info</property>.
+ *
+ * <p>
+ * Required. Provides metadata about the API.
+ *
+ * <p>
+ * The metadata can be used by the clients if needed.
+ *
+ * @param info The new value for the <property>info</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Swagger setInfo(Info info) {
+ this.info = info;
+ return this;
+ }
+
+ /**
+ * Synonym for {@link #setInfo(Info)}.
+ *
+ * @param info The new value for the <property>info</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Swagger info(Info info) {
+ return setInfo(info);
+ }
+
+ /**
+ * Bean property getter: <property>host</property>.
+ *
+ * <p>
+ * The host (name or IP) serving the API.
+ *
+ * <p>
+ * This MUST be the host only and does not include the scheme nor sub-paths.
+ * It MAY include a port.
+ * If the host is not included, the host serving the documentation is to be used (including the port).
+ * The host does not support <a class="doclink" href="http://swagger.io/specification/#pathTemplating">
+ * path templating</a>.
+ *
+ * @return The value of the <property>host</property> property on this bean, or <jk>null</jk> if it is not set.
+ */
+ public String getHost() {
+ return host;
+ }
+
+ /**
+ * Bean property setter: <property>host</property>.
+ *
+ * <p>
+ * The host (name or IP) serving the API.
+ *
+ * <p>
+ * This MUST be the host only and does not include the scheme nor sub-paths.
+ * It MAY include a port.
+ * If the host is not included, the host serving the documentation is to be used (including the port).
+ * The host does not support <a class="doclink" href="http://swagger.io/specification/#pathTemplating">
+ * path templating</a>.
+ *
+ * @param host The new value for the <property>host</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Swagger setHost(String host) {
+ this.host = host;
+ return this;
+ }
+
+ /**
+ * Synonym for {@link #setHost(String)}.
+ *
+ * @param host The new value for the <property>host</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Swagger host(String host) {
+ return setHost(host);
+ }
+
+ /**
+ * Bean property getter: <property>basePath</property>.
+ *
+ * <p>
+ * The base path on which the API is served, which is relative to the <code>host</code>.
+ *
+ * <p>
+ * If it is not included, the API is served directly under the <code>host</code>.
+ * The value MUST start with a leading slash (/).
+ * The <code>basePath</code> does not support <a class="doclink"
+ * href="http://swagger.io/specification/#pathTemplating">path templating</a>.
+ *
+ * @return The value of the <property>basePath</property> property on this bean, or <jk>null</jk> if it is not set.
+ */
+ public String getBasePath() {
+ return basePath;
+ }
+
+ /**
+ * Bean property setter: <property>basePath</property>.
+ *
+ * <p>
+ * The base path on which the API is served, which is relative to the <code>host</code>.
+ *
+ * <p>
+ * If it is not included, the API is served directly under the <code>host</code>.
+ * The value MUST start with a leading slash (/).
+ * The <code>basePath</code> does not support <a class="doclink"
+ * href="http://swagger.io/specification/#pathTemplating">path templating</a>.
+ *
+ * @param basePath The new value for the <property>basePath</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Swagger setBasePath(String basePath) {
+ this.basePath = basePath;
+ return this;
+ }
+
+ /**
+ * Synonym for {@link #setBasePath(String)}.
+ *
+ * @param basePath The new value for the <property>basePath</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Swagger basePath(String basePath) {
+ return setBasePath(basePath);
+ }
+
+ /**
+ * Bean property getter: <property>schemes</property>.
+ *
+ * <p>
+ * The transfer protocol of the API.
+ *
+ * <p>
+ * Values MUST be from the list: <js>"http"</js>, <js>"https"</js>, <js>"ws"</js>, <js>"wss"</js>.
+ * If the <code>schemes</code> is not included, the default scheme to be used is the one used to access the Swagger
+ * definition itself.
+ *
+ * @return The value of the <property>schemes</property> property on this bean, or <jk>null</jk> if it is not set.
+ */
+ public List<String> getSchemes() {
+ return schemes;
+ }
+
+ /**
+ * Bean property setter: <property>schemes</property>.
+ *
+ * <p>
+ * The transfer protocol of the API.
+ *
+ * <p>
+ * Values MUST be from the list: <js>"http"</js>, <js>"https"</js>, <js>"ws"</js>, <js>"wss"</js>.
+ * If the <code>schemes</code> is not included, the default scheme to be used is the one used to access the Swagger
+ * definition itself.
+ *
+ * @param schemes The new value for the <property>schemes</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Swagger setSchemes(List<String> schemes) {
+ this.schemes = schemes;
+ return this;
+ }
+
+ /**
+ * Bean property adder: <property>schemes</property>.
+ *
+ * <p>
+ * The transfer protocol of the API.
+ *
+ * <p>
+ * Values MUST be from the list: <js>"http"</js>, <js>"https"</js>, <js>"ws"</js>, <js>"wss"</js>.
+ * If the <code>schemes</code> is not included, the default scheme to be used is the one used to access the Swagger
+ * definition itself.
+ *
+ * @param schemes The values to add for the <property>schemes</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Swagger addSchemes(String...schemes) {
+ return addSchemes(Arrays.asList(schemes));
+ }
+
+ /**
+ * Bean property adder: <property>schemes</property>.
+ *
+ * <p>
+ * The transfer protocol of the API.
+ *
+ * <p>
+ * Values MUST be from the list: <js>"http"</js>, <js>"https"</js>, <js>"ws"</js>, <js>"wss"</js>.
+ * If the <code>schemes</code> is not included, the default scheme to be used is the one used to access the Swagger
+ * definition itself.
+ *
+ * @param schemes The values to add for the <property>schemes</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Swagger addSchemes(Collection<String> schemes) {
+ if (schemes != null) {
+ if (this.schemes == null)
+ this.schemes = new LinkedList<String>();
+ this.schemes.addAll(schemes);
+ }
+ return this;
+ }
+
+ /**
+ * Synonym for {@link #addSchemes(String...)}.
+ *
+ * @param schemes The values to add for the <property>schemes</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Swagger schemes(String...schemes) {
+ return addSchemes(schemes);
+ }
+
+ /**
+ * Bean property getter: <property>consumes</property>.
+ *
+ * <p>
+ * A list of MIME types the APIs can consume.
+ *
+ * <p>
+ * This is global to all APIs but can be overridden on specific API calls.
+ * Value MUST be as described under <a class="doclink" href="http://swagger.io/specification/#mimeTypes">
+ * Mime Types</a>.
+ *
+ * @return The value of the <property>consumes</property> property on this bean, or <jk>null</jk> if it is not set.
+ */
+ public List<MediaType> getConsumes() {
+ return consumes;
+ }
+
+ /**
+ * Bean property setter: <property>consumes</property>.
+ *
+ * <p>
+ * A list of MIME types the APIs can consume.
+ *
+ * <p>
+ * This is global to all APIs but can be overridden on specific API calls.
+ * Value MUST be as described under <a class="doclink" href="http://swagger.io/specification/#mimeTypes">
+ * Mime Types</a>.
+ *
+ * @param consumes The new value for the <property>consumes</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Swagger setConsumes(List<MediaType> consumes) {
+ this.consumes = consumes;
+ return this;
+ }
+
+ /**
+ * Bean property adder: <property>consumes</property>.
+ *
+ * <p>
+ * A list of MIME types the APIs can consume.
+ *
+ * <p>
+ * This is global to all APIs but can be overridden on specific API calls.
+ * Value MUST be as described under <a class="doclink" href="http://swagger.io/specification/#mimeTypes">
+ * Mime Types</a>.
+ *
+ * @param consumes The values to add for the <property>consumes</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Swagger addConsumes(MediaType...consumes) {
+ return addConsumes(Arrays.asList(consumes));
+ }
+
+ /**
+ * Bean property adder: <property>consumes</property>.
+ *
+ * <p>
+ * A list of MIME types the APIs can consume.
+ *
+ * <p>
+ * This is global to all APIs but can be overridden on specific API calls.
+ * Value MUST be as described under <a class="doclink" href="http://swagger.io/specification/#mimeTypes">
+ * Mime Types</a>.
+ *
+ * @param consumes The values to add for the <property>consumes</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Swagger addConsumes(Collection<MediaType> consumes) {
+ if (consumes != null) {
+ if (this.consumes == null)
+ this.consumes = new LinkedList<MediaType>();
+ this.consumes.addAll(consumes);
+ }
+ return this;
+ }
+
+ /**
+ * Synonym for {@link #addConsumes(MediaType...)}.
+ *
+ * @param consumes The values to add for the <property>consumes</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Swagger consumes(MediaType...consumes) {
+ return addConsumes(consumes);
+ }
+
+ /**
+ * Synonym for {@link #addConsumes(Collection)}.
+ *
+ * @param consumes The values to add for the <property>consumes</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Swagger consumes(Collection<MediaType> consumes) {
+ return addConsumes(consumes);
+ }
+
+ /**
+ * Bean property getter: <property>produces</property>.
+ *
+ * <p>
+ * A list of MIME types the APIs can produce.
+ *
+ * <p>
+ * This is global to all APIs but can be overridden on specific API calls.
+ * Value MUST be as described under <a class="doclink" href="http://swagger.io/specification/#mimeTypes">
+ * Mime Types</a>.
+ *
+ * @return The value of the <property>produces</property> property on this bean, or <jk>null</jk> if it is not set.
+ */
+ public List<MediaType> getProduces() {
+ return produces;
+ }
+
+ /**
+ * Bean property setter: <property>produces</property>.
+ *
+ * <p>
+ * A list of MIME types the APIs can produce.
+ *
+ * <p>
+ * This is global to all APIs but can be overridden on specific API calls.
+ * Value MUST be as described under <a class="doclink" href="http://swagger.io/specification/#mimeTypes">
+ * Mime Types</a>.
+ *
+ * @param produces The new value for the <property>produces</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Swagger setProduces(List<MediaType> produces) {
+ this.produces = produces;
+ return this;
+ }
+
+ /**
+ * Bean property adder: <property>produces</property>.
+ *
+ * <p>
+ * A list of MIME types the APIs can produce.
+ *
+ * <p>
+ * This is global to all APIs but can be overridden on specific API calls.
+ * Value MUST be as described under <a class="doclink" href="http://swagger.io/specification/#mimeTypes">
+ * Mime Types</a>.
+ *
+ * @param produces The values to add for the <property>produces</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Swagger addProduces(MediaType...produces) {
+ return addProduces(Arrays.asList(produces));
+ }
+
+ /**
+ * Bean property adder: <property>produces</property>.
+ *
+ * <p>
+ * A list of MIME types the APIs can produce.
+ *
+ * <p>
+ * This is global to all APIs but can be overridden on specific API calls.
+ * Value MUST be as described under <a class="doclink" href="http://swagger.io/specification/#mimeTypes">
+ * Mime Types</a>.
+ *
+ * @param produces The values to add for the <property>produces</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Swagger addProduces(Collection<MediaType> produces) {
+ if (produces != null) {
+ if (this.produces == null)
+ this.produces = new LinkedList<MediaType>();
+ this.produces.addAll(produces);
+ }
+ return this;
+ }
+
+ /**
+ * Synonym for {@link #addProduces(MediaType...)}.
+ *
+ * @param produces The values to add for the <property>produces</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Swagger produces(MediaType...produces) {
+ return addProduces(produces);
+ }
+
+ /**
+ * Synonym for {@link #addProduces(Collection)}.
+ *
+ * @param produces The values to add for the <property>produces</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Swagger produces(Collection<MediaType> produces) {
+ return addProduces(produces);
+ }
+
+ /**
+ * Bean property getter: <property>paths</property>.
+ *
+ * <p>
+ * Required. The available paths and operations for the API.
+ *
+ * @return The value of the <property>paths</property> property on this bean, or <jk>null</jk> if it is not set.
+ */
+ public Map<String,Map<String,Operation>> getPaths() {
+ return paths;
+ }
+
+ /**
+ * Bean property setter: <property>paths</property>.
+ *
+ * <p>
+ * Required. The available paths and operations for the API.
+ *
+ * @param paths The new value for the <property>paths</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Swagger setPaths(Map<String,Map<String,Operation>> paths) {
+ this.paths = paths;
+ return this;
+ }
+
+ /**
+ * Bean property adder: <property>paths</property>.
+ *
+ * <p>
+ * Required. The available paths and operations for the API.
+ *
+ * @param path The path template.
+ * @param methodName The HTTP method name.
+ * @param operation The operation that describes the path.
+ * @return This object (for method chaining).
+ */
+ public Swagger addPath(String path, String methodName, Operation operation) {
+ if (paths == null)
+ paths = new TreeMap<String,Map<String,Operation>>();
+ Map<String,Operation> p = paths.get(path);
+ if (p == null) {
+ p = new TreeMap<String,Operation>(new MethodSorter());
+ paths.put(path, p);
+ }
+ p.put(methodName, operation);
+ return this;
+ }
+
+ /**
+ * Synonym for {@link #path(String,String,Operation)}.
+ *
+ * @param path The path template.
+ * @param methodName The HTTP method name.
+ * @param operation The operation that describes the path.
+ * @return This object (for method chaining).
+ */
+ public Swagger path(String path, String methodName, Operation operation) {
+ return addPath(path, methodName, operation);
+ }
+
+ /**
+ * Bean property getter: <property>definitions</property>.
+ *
+ * <p>
+ * An object to hold data types produced and consumed by operations.
+ *
+ * @return
+ * The value of the <property>definitions</property> property on this bean, or <jk>null</jk> if it is not set.
+ */
+ public Map<String,SchemaInfo> getDefinitions() {
+ return definitions;
+ }
+
+ /**
+ * Bean property setter: <property>definitions</property>.
+ *
+ * <p>
+ * An object to hold data types produced and consumed by operations.
+ *
+ * @param definitions The new value for the <property>definitions</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Swagger setDefinitions(Map<String,SchemaInfo> definitions) {
+ this.definitions = definitions;
+ return this;
+ }
+
+ /**
+ * Bean property adder: <property>definitions</property>.
+ *
+ * <p>
+ * An object to hold data types produced and consumed by operations.
+ *
+ * @param name A definition name.
+ * @param schema The schema that the name defines.
+ * @return This object (for method chaining).
+ */
+ public Swagger addDefinition(String name, SchemaInfo schema) {
+ if (definitions == null)
+ definitions = new TreeMap<String,SchemaInfo>();
+ definitions.put(name, schema);
+ return this;
+ }
+
+ /**
+ * Synonym for {@link #addDefinition(String,SchemaInfo)}.
+ *
+ * @param name A definition name.
+ * @param schema The schema that the name defines.
+ * @return This object (for method chaining).
+ */
+ public Swagger xxx(String name, SchemaInfo schema) {
+ return addDefinition(name, schema);
+ }
+
+ /**
+ * Bean property getter: <property>parameters</property>.
+ *
+ * <p>
+ * An object to hold parameters that can be used across operations.
+ *
+ * <p>
+ * This property does not define global parameters for all operations.
+ *
+ * @return The value of the <property>parameters</property> property on this bean, or <jk>null</jk> if it is not set.
+ */
+ public Map<String,ParameterInfo> getParameters() {
+ return parameters;
+ }
+
+ /**
+ * Bean property setter: <property>parameters</property>.
+ *
+ * <p>
+ * An object to hold parameters that can be used across operations.
+ *
+ * <p>
+ * This property does not define global parameters for all operations.
+ *
+ * @param parameters The new value for the <property>parameters</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Swagger setParameters(Map<String,ParameterInfo> parameters) {
+ this.parameters = parameters;
+ return this;
+ }
+
+ /**
+ * Bean property adder: <property>parameters</property>.
+ *
+ * <p>
+ * An object to hold parameters that can be used across operations.
+ *
+ * <p>
+ * This property does not define global parameters for all operations.
+ *
+ * @param name The parameter name.
+ * @param parameter The parameter definition.
+ * @return This object (for method chaining).
+ */
+ public Swagger addParameter(String name, ParameterInfo parameter) {
+ if (parameters == null)
+ parameters = new TreeMap<String,ParameterInfo>();
+ parameters.put(name, parameter);
+ return this;
+ }
+
+ /**
+ * Synonym for {@link #addParameter(String,ParameterInfo)}.
+ *
+ * @param name The parameter name.
+ * @param parameter The parameter definition.
+ * @return This object (for method chaining).
+ */
+ public Swagger parameter(String name, ParameterInfo parameter) {
+ return addParameter(name, parameter);
+ }
+
+ /**
+ * Bean property getter: <property>responses</property>.
+ *
+ * <p>
+ * An object to hold responses that can be used across operations.
+ *
+ * <p>
+ * This property does not define global responses for all operations.
+ *
+ * @return The value of the <property>responses</property> property on this bean, or <jk>null</jk> if it is not set.
+ */
+ public Map<String,ResponseInfo> getResponses() {
+ return responses;
+ }
+
+ /**
+ * Bean property setter: <property>responses</property>.
+ *
+ * <p>
+ * An object to hold responses that can be used across operations.
+ *
+ * <p>
+ * This property does not define global responses for all operations.
+ *
+ * @param responses The new value for the <property>responses</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Swagger setResponses(Map<String,ResponseInfo> responses) {
+ this.responses = responses;
+ return this;
+ }
+
+ /**
+ * Bean property adder: <property>responses</property>.
+ *
+ * <p>
+ * An object to hold responses that can be used across operations.
+ *
+ * <p>
+ * This property does not define global responses for all operations.
+ *
+ * @param name The response name.
+ * @param response The response definition.
+ * @return This object (for method chaining).
+ */
+ public Swagger addResponse(String name, ResponseInfo response) {
+ if (responses == null)
+ responses = new TreeMap<String,ResponseInfo>();
+ responses.put(name, response);
+ return this;
+ }
+
+ /**
+ * Synonym for {@link #addResponse(String,ResponseInfo)}.
+ *
+ * @param name The response name.
+ * @param response The response definition.
+ * @return This object (for method chaining).
+ */
+ public Swagger response(String name, ResponseInfo response) {
+ return addResponse(name, response);
+ }
+
+ /**
+ * Bean property getter: <property>securityDefinitions</property>.
+ *
+ * <p>
+ * Security scheme definitions that can be used across the specification.
+ *
+ * @return
+ * The value of the <property>securityDefinitions</property> property on this bean, or <jk>null</jk> if it
+ * is not set.
+ */
+ public Map<String,SecurityScheme> getSecurityDefinitions() {
+ return securityDefinitions;
+ }
+
+ /**
+ * Bean property setter: <property>securityDefinitions</property>.
+ *
+ * <p>
+ * Security scheme definitions that can be used across the specification.
+ *
+ * @param securityDefinitions The new value for the <property>securityDefinitions</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Swagger setSecurityDefinitions(Map<String,SecurityScheme> securityDefinitions) {
+ this.securityDefinitions = securityDefinitions;
+ return this;
+ }
+
+ /**
+ * Bean property adder: <property>securityDefinitions</property>.
+ *
+ * <p>
+ * Security scheme definitions that can be used across the specification.
+ *
+ * @param name A security name.
+ * @param securityScheme A security schema.
+ * @return This object (for method chaining).
+ */
+ public Swagger addSecurityDefinition(String name, SecurityScheme securityScheme) {
+ if (securityDefinitions == null)
+ securityDefinitions = new TreeMap<String,SecurityScheme>();
+ securityDefinitions.put(name, securityScheme);
+ return this;
+ }
+
+ /**
+ * Synonym for {@link #addSecurityDefinition(String,SecurityScheme)}.
+ *
+ * @param name A security name.
+ * @param securityScheme A security schema.
+ * @return This object (for method chaining).
+ */
+ public Swagger securityDefinition(String name, SecurityScheme securityScheme) {
+ return addSecurityDefinition(name, securityScheme);
+ }
+
+ /**
+ * Bean property getter: <property>security</property>.
+ *
+ * <p>
+ * A declaration of which security schemes are applied for the API as a whole.
+ *
+ * <p>
+ * The list of values describes alternative security schemes that can be used (that is, there is a logical OR
+ * between the security requirements).
+ * Individual operations can override this definition.
+ *
+ * @return The value of the <property>security</property> property on this bean, or <jk>null</jk> if it is not set.
+ */
+ public List<Map<String,List<String>>> getSecurity() {
+ return security;
+ }
+
+ /**
+ * Bean property setter: <property>security</property>.
+ *
+ * <p>
+ * A declaration of which security schemes are applied for the API as a whole.
+ *
+ * <p>
+ * The list of values describes alternative security schemes that can be used (that is, there is a logical OR
+ * between the security requirements).
+ * Individual operations can override this definition.
+ *
+ * @param security The new value for the <property>security</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Swagger setSecurity(List<Map<String,List<String>>> security) {
+ this.security = security;
+ return this;
+ }
+
+ /**
+ * Bean property adder: <property>security</property>.
+ *
+ * <p>
+ * A declaration of which security schemes are applied for the API as a whole.
+ *
+ * <p>
+ * The list of values describes alternative security schemes that can be used (that is, there is a logical OR
+ * between the security requirements).
+ * Individual operations can override this definition.
+ *
+ * @param security The value to add for the <property>security</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Swagger addSecurity(Map<String,List<String>> security) {
+ if (this.security == null)
+ this.security = new LinkedList<Map<String,List<String>>>();
+ this.security.add(security);
+ return this;
+ }
+
+ /**
+ * Synonym for {@link #addSecurity(Map)}.
+ *
+ * @param scheme The security scheme that applies to this operation
+ * @param alternatives The list of values describes alternative security schemes that can be used (that is, there
+ * is a logical OR between the security requirements).
+ * @return This object (for method chaining).
+ */
+ public Swagger security(String scheme, String...alternatives) {
+ Map<String,List<String>> m = new LinkedHashMap<String,List<String>>();
+ m.put(scheme, Arrays.asList(alternatives));
+ return addSecurity(m);
+ }
+
+ /**
+ * Bean property getter: <property>tags</property>.
+ *
+ * <p>
+ * A list of tags used by the specification with additional metadata.
+ *
+ * <p>
+ * The order of the tags can be used to reflect on their order by the parsing tools.
+ * Not all tags that are used by the <a class="doclink" href="http://swagger.io/specification/#operationObject">
+ * Operation Object</a> must be declared.
+ * The tags that are not declared may be organized randomly or based on the tools' logic.
+ * Each tag name in the list MUST be unique.
+ *
+ * @return The value of the <property>tags</property> property on this bean, or <jk>null</jk> if it is not set.
+ */
+ public List<Tag> getTags() {
+ return tags;
+ }
+
+ /**
+ * Bean property setter: <property>tags</property>.
+ *
+ * <p>
+ * A list of tags used by the specification with additional metadata.
+ *
+ * <p>
+ * The order of the tags can be used to reflect on their order by the parsing tools.
+ * Not all tags that are used by the <a class="doclink" href="http://swagger.io/specification/#operationObject">
+ * Operation Object</a> must be declared.
+ * The tags that are not declared may be organized randomly or based on the tools' logic.
+ * Each tag name in the list MUST be unique.
+ *
+ * @param tags The new value for the <property>tags</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Swagger setTags(List<Tag> tags) {
+ this.tags = tags;
+ return this;
+ }
+
+ /**
+ * Bean property adder: <property>tags</property>.
+ *
+ * <p>
+ * A list of tags used by the specification with additional metadata.
+ *
+ * <p>
+ * The order of the tags can be used to reflect on their order by the parsing tools.
+ * Not all tags that are used by the <a class="doclink" href="http://swagger.io/specification/#operationObject">
+ * Operation Object</a> must be declared.
+ * The tags that are not declared may be organized randomly or based on the tools' logic.
+ * Each tag name in the list MUST be unique.
+ *
+ * @param tags The values to add for the <property>tags</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Swagger addTags(Tag...tags) {
+ if (this.tags == null)
+ this.tags = new LinkedList<Tag>();
+ this.tags.addAll(Arrays.asList(tags));
+ return this;
+ }
+
+ /**
+ * Synonym for {@link #addTags(Tag...)}.
+ *
+ * @param tags The values to add for the <property>tags</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Swagger tags(Tag...tags) {
+ return addTags(tags);
+ }
+
+ /**
+ * Synonym for {@link #setTags(List)}.
+ *
+ * @param tags The values to add for the <property>tags</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Swagger tags(List<Tag> tags) {
+ return setTags(tags);
+ }
+
+ /**
+ * Bean property getter: <property>externalDocs</property>.
+ *
+ * <p>
+ * Additional external documentation.
+ *
+ * @return
+ * The value of the <property>externalDocs</property> property on this bean, or <jk>null</jk> if it is
+ * not set.
+ */
+ public ExternalDocumentation getExternalDocs() {
+ return externalDocs;
+ }
+
+ /**
+ * Bean property setter: <property>externalDocs</property>.
+ *
+ * <p>
+ * Additional external documentation.
+ *
+ * @param externalDocs The new value for the <property>externalDocs</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Swagger setExternalDocs(ExternalDocumentation externalDocs) {
+ this.externalDocs = externalDocs;
+ return this;
+ }
+
+ /**
+ * Synonym for {@link #setExternalDocs(ExternalDocumentation)}.
+ *
+ * @param externalDocs The new value for the <property>externalDocs</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Swagger externalDocs(ExternalDocumentation externalDocs) {
+ return setExternalDocs(externalDocs);
+ }
+
+ private static class MethodSorter implements Comparator<String> {
+ private final Map<String,Integer> methods = new AMap<String,Integer>()
+ .append("get",7)
+ .append("put",6)
+ .append("post",5)
+ .append("delete",4)
+ .append("options",3)
+ .append("head",2)
+ .append("patch",1);
+
+ @Override
+ public int compare(String o1, String o2) {
+ Integer i1 = methods.get(o1);
+ Integer i2 = methods.get(o2);
+ if (i1 == null)
+ i1 = 0;
+ if (i2 == null)
+ i2 = 0;
+ return i2.compareTo(i1);
+ }
+ }
+}
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/75b0d8ee/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/SwaggerBuilder.java
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/SwaggerBuilder.java b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/SwaggerBuilder.java
new file mode 100644
index 0000000..9e96614
--- /dev/null
+++ b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/SwaggerBuilder.java
@@ -0,0 +1,358 @@
+// ***************************************************************************************************************************
+// * 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.dto.swagger;
+
+import java.net.*;
+
+import org.apache.juneau.*;
+
+/**
+ * Various useful static methods for creating Swagger elements.
+ *
+ * <h6 class='topic'>Additional Information</h6>
+ * <ul class='doctree'>
+ * <li class='link'>
+ * <a class='doclink' href='../../../../../overview-summary.html#DTOs'>Juneau Data Transfer Objects
+ * (org.apache.juneau.dto)</a>
+ * <ul>
+ * <li class='sublink'>
+ * <a class='doclink' href='../../../../../overview-summary.html#DTOs.Swagger'>Swagger</a>
+ * </ul>
+ * </li>
+ * <li class='jp'>
+ * <a class='doclink' href='package-summary.html#TOC'>org.apache.juneau.dto.swagger</a>
+ * </li>
+ * </ul>
+ */
+public class SwaggerBuilder {
+
+ /**
+ * Creates an empty {@link Contact} element.
+ *
+ * @return The new element.
+ */
+ public static final Contact contact() {
+ return new Contact();
+ }
+
+ /**
+ * Creates an {@link Contact} element with the specified {@link Contact#name(String)} attribute.
+ *
+ * @param name The {@link Contact#name(String)} attribute.
+ * @return The new element.
+ */
+ public static final Contact contact(String name) {
+ return contact().name(name);
+ }
+
+ /**
+ * Creates an {@link Contact} element with the specified {@link Contact#name(String)}, {@link Contact#url(Object)},
+ * and {@link Contact#email(String)}, attributes.
+ *
+ * @param name The {@link Contact#name(String)} attribute.
+ * @param url
+ * The {@link Contact#url(Object)} attribute.
+ * The value can be of any of the following types: {@link URI}, {@link URL}, {@link String}.
+ * <br>Strings must be valid URIs.
+ * <br>URIs defined by {@link UriResolver} can be used for values.
+ * @param email The {@link Contact#email(String)} attribute.
+ * @return The new element.
+ */
+ public static final Contact contact(String name, Object url, String email) {
+ return contact().name(name).url(url).email(email);
+ }
+
+ /**
+ * Creates an empty {@link ExternalDocumentation} element.
+ *
+ * @return The new element.
+ */
+ public static final ExternalDocumentation externalDocumentation() {
+ return new ExternalDocumentation();
+ }
+
+ /**
+ * Creates an {@link ExternalDocumentation} element with the specified {@link ExternalDocumentation#url(Object)}
+ * attribute.
+ *
+ * @param url
+ * The {@link ExternalDocumentation#url(Object)} attribute.
+ * The value can be of any of the following types: {@link URI}, {@link URL}, {@link String}.
+ * <br>Strings must be valid URIs.
+ * <br>URIs defined by {@link UriResolver} can be used for values.
+ * @return The new element.
+ */
+ public static final ExternalDocumentation externalDocumentation(Object url) {
+ return externalDocumentation().url(url);
+ }
+
+ /**
+ * Creates an {@link ExternalDocumentation} element with the specified {@link ExternalDocumentation#url(Object)}
+ * and {@link ExternalDocumentation#description(String)} attributes.
+ *
+ * @param url
+ * The {@link ExternalDocumentation#url(Object)} attribute.
+ * The value can be of any of the following types: {@link URI}, {@link URL}, {@link String}.
+ * <br>Strings must be valid URIs.
+ * <br>URIs defined by {@link UriResolver} can be used for values.
+ * @param description The {@link ExternalDocumentation#description(String)} attribute.
+ * @return The new element.
+ */
+ public static final ExternalDocumentation externalDocumentation(Object url, String description) {
+ return externalDocumentation().url(url).description(description);
+ }
+
+ /**
+ * Creates an empty {@link HeaderInfo} element.
+ *
+ * @return The new element.
+ */
+ public static final HeaderInfo headerInfo() {
+ return new HeaderInfo();
+ }
+
+ /**
+ * Creates an {@link HeaderInfo} element with the specified {@link HeaderInfo#type(String)} attribute.
+ *
+ * @param type The {@link HeaderInfo#type(String)} attribute.
+ * @return The new element.
+ */
+ public static final HeaderInfo headerInfo(String type) {
+ return headerInfo().type(type);
+ }
+
+ /**
+ * Creates an {@link HeaderInfo} element with the specified {@link HeaderInfo#type(String)} attribute.
+ *
+ * @param type The {@link HeaderInfo#type(String)} attribute.
+ * @return The new element.
+ */
+ public static final HeaderInfo headerInfoStrict(String type) {
+ return headerInfo().strict().type(type);
+ }
+
+ /**
+ * Creates an empty {@link Info} element.
+ *
+ * @return The new element.
+ */
+ public static final Info info() {
+ return new Info();
+ }
+
+ /**
+ * Creates an {@link Info} element with the specified {@link Info#title(String)} and {@link Info#version(String)}
+ * attributes.
+ *
+ * @param title The {@link Info#title(String)} attribute.
+ * @param version The {@link Info#version(String)} attribute.
+ * @return The new element.
+ */
+ public static final Info info(String title, String version) {
+ return info().title(title).version(version);
+ }
+
+ /**
+ * Creates an empty {@link Items} element.
+ *
+ * @return The new element.
+ */
+ public static final Items items() {
+ return new Items();
+ }
+
+ /**
+ * Creates an {@link Items} element with the specified {@link Items#type(String)} attribute.
+ *
+ * @param type The {@link Items#type(String)} attribute.
+ * @return The new element.
+ */
+ public static final Items items(String type) {
+ return items().type(type);
+ }
+
+ /**
+ * Creates an {@link Items} element with the specified {@link Items#type(String)} attribute.
+ *
+ * @param type The {@link Items#type(String)} attribute.
+ * @return The new element.
+ */
+ public static final Items itemsStrict(String type) {
+ return items().strict().type(type);
+ }
+
+ /**
+ * Creates an empty {@link License} element.
+ *
+ * @return The new element.
+ */
+ public static final License license() {
+ return new License();
+ }
+
+ /**
+ * Creates an {@link License} element with the specified {@link License#name(String)} attribute.
+ *
+ * @param name The {@link License#name(String)} attribute.
+ * @return The new element.
+ */
+ public static final License license(String name) {
+ return license().name(name);
+ }
+
+ /**
+ * Creates an empty {@link Operation} element.
+ *
+ * @return The new element.
+ */
+ public static final Operation operation() {
+ return new Operation();
+ }
+
+ /**
+ * Creates an empty {@link ParameterInfo} element.
+ *
+ * @return The new element.
+ */
+ public static final ParameterInfo parameterInfo() {
+ return new ParameterInfo();
+ }
+
+ /**
+ * Creates an {@link ParameterInfo} element with the specified {@link ParameterInfo#in(String)} and
+ * {@link ParameterInfo#name(String)} attributes.
+ *
+ * @param in The {@link ParameterInfo#in(String)} attribute.
+ * @param name The {@link ParameterInfo#name(String)} attribute.
+ * @return The new element.
+ */
+ public static final ParameterInfo parameterInfo(String in, String name) {
+ return parameterInfo().in(in).name(name);
+ }
+
+ /**
+ * Creates an {@link ParameterInfo} element with the specified {@link ParameterInfo#in(String)} and
+ * {@link ParameterInfo#name(String)} attributes.
+ *
+ * @param in The {@link ParameterInfo#in(String)} attribute.
+ * @param name The {@link ParameterInfo#name(String)} attribute.
+ * @return The new element.
+ */
+ public static final ParameterInfo parameterInfoStrict(String in, String name) {
+ return parameterInfo().strict().in(in).name(name);
+ }
+
+ /**
+ * Creates an empty {@link ResponseInfo} element.
+ *
+ * @return The new element.
+ */
+ public static final ResponseInfo responseInfo() {
+ return new ResponseInfo();
+ }
+
+ /**
+ * Creates an {@link ResponseInfo} element with the specified {@link ResponseInfo#description(String)} attribute.
+ *
+ * @param description The {@link ResponseInfo#description(String)} attribute.
+ * @return The new element.
+ */
+ public static final ResponseInfo responseInfo(String description) {
+ return responseInfo().description(description);
+ }
+
+ /**
+ * Creates an empty {@link SchemaInfo} element.
+ *
+ * @return The new element.
+ */
+ public static final SchemaInfo schemaInfo() {
+ return new SchemaInfo();
+ }
+
+ /**
+ * Creates an empty {@link SecurityScheme} element.
+ *
+ * @return The new element.
+ */
+ public static final SecurityScheme securityScheme() {
+ return new SecurityScheme();
+ }
+
+ /**
+ * Creates an {@link SecurityScheme} element with the specified {@link SecurityScheme#type(String)} attribute.
+ *
+ * @param type The {@link SecurityScheme#type(String)} attribute.
+ * @return The new element.
+ */
+ public static final SecurityScheme securityScheme(String type) {
+ return securityScheme().type(type);
+ }
+
+ /**
+ * Creates an {@link SecurityScheme} element with the specified {@link SecurityScheme#type(String)} attribute.
+ *
+ * @param type The {@link SecurityScheme#type(String)} attribute.
+ * @return The new element.
+ */
+ public static final SecurityScheme securitySchemeStrict(String type) {
+ return securityScheme().strict().type(type);
+ }
+
+ /**
+ * Creates an empty {@link Swagger} element.
+ *
+ * @return The new element.
+ */
+ public static final Swagger swagger() {
+ return new Swagger();
+ }
+
+ /**
+ * Creates an {@link Swagger} element with the specified {@link Swagger#info(Info)} attribute.
+ *
+ * @param info The {@link Swagger#info(Info)} attribute.
+ * @return The new element.
+ */
+ public static final Swagger swagger(Info info) {
+ return swagger().info(info);
+ }
+
+ /**
+ * Creates an empty {@link Tag} element.
+ *
+ * @return The new element.
+ */
+ public static final Tag tag() {
+ return new Tag();
+ }
+
+ /**
+ * Creates an {@link Tag} element with the specified {@link Tag#name(String)} attribute.
+ *
+ * @param name The {@link Tag#name(String)} attribute.
+ * @return The new element.
+ */
+ public static final Tag tag(String name) {
+ return tag().name(name);
+ }
+
+ /**
+ * Creates an empty {@link Xml} element.
+ *
+ * @return The new element.
+ */
+ public static final Xml xml() {
+ return new Xml();
+ }
+}
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/75b0d8ee/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/SwaggerElement.java
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/SwaggerElement.java b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/SwaggerElement.java
new file mode 100644
index 0000000..ed41bdd
--- /dev/null
+++ b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/SwaggerElement.java
@@ -0,0 +1,55 @@
+// ***************************************************************************************************************************
+// * 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.dto.swagger;
+
+/**
+ * Root class for all Swagger beans.
+ *
+ * <h6 class='topic'>Additional Information</h6>
+ * <ul class='doctree'>
+ * <li class='link'>
+ * <a class='doclink' href='../../../../../overview-summary.html#DTOs'>Juneau Data Transfer Objects
+ * (org.apache.juneau.dto)</a>
+ * <ul>
+ * <li class='sublink'>
+ * <a class='doclink' href='../../../../../overview-summary.html#DTOs.Swagger'>Swagger</a>
+ * </ul>
+ * </li>
+ * <li class='jp'>
+ * <a class='doclink' href='package-summary.html#TOC'>org.apache.juneau.dto.swagger</a>
+ * </li>
+ * </ul>
+ */
+public class SwaggerElement {
+
+ private boolean strict;
+
+ /**
+ * Returns <jk>true</jk> if contents should be validated per the Swagger spec.
+ *
+ * @return <jk>true</jk> if contents should be validated per the Swagger spec.
+ */
+ protected boolean isStrict() {
+ return strict;
+ }
+
+ /**
+ * Sets strict mode on this bean.
+ *
+ * @return This object (for method chaining).
+ */
+ protected SwaggerElement strict() {
+ this.strict = true;
+ return this;
+ }
+}
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/75b0d8ee/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/Tag.java
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/Tag.java b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/Tag.java
new file mode 100644
index 0000000..3e97616
--- /dev/null
+++ b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/Tag.java
@@ -0,0 +1,171 @@
+// ***************************************************************************************************************************
+// * 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.dto.swagger;
+
+import org.apache.juneau.annotation.*;
+
+/**
+ * Allows adding meta data to a single tag that is used by the <a class="doclink" href="http://swagger.io/specification/#operationObject">Operation Object</a>.
+ *
+ * <p>
+ * It is not mandatory to have a Tag Object per tag used there.
+ *
+ * <h5 class='section'>Example:</h5>
+ * <p class='bcode'>
+ * {
+ * <js>"name"</js>: <js>"pet"</js>,
+ * <js>"description"</js>: <js>"Pets operations"</js>
+ * }
+ * </p>
+ *
+ * <h6 class='topic'>Additional Information</h6>
+ * <ul class='doctree'>
+ * <li class='link'>
+ * <a class='doclink' href='../../../../../overview-summary.html#DTOs'>Juneau Data Transfer Objects
+ * (org.apache.juneau.dto)</a>
+ * <ul>
+ * <li class='sublink'>
+ * <a class='doclink' href='../../../../../overview-summary.html#DTOs.Swagger'>Swagger</a>
+ * </ul>
+ * </li>
+ * <li class='jp'>
+ * <a class='doclink' href='package-summary.html#TOC'>org.apache.juneau.dto.swagger</a>
+ * </li>
+ * </ul>
+ */
+@Bean(properties="name,description,externalDocs")
+@SuppressWarnings("hiding")
+public class Tag extends SwaggerElement {
+
+ private String name;
+ private String description;
+ private ExternalDocumentation externalDocs;
+
+ /**
+ * Bean property getter: <property>name</property>.
+ *
+ * <p>
+ * Required. The name of the tag.
+ *
+ * @return The value of the <property>name</property> property on this bean, or <jk>null</jk> if it is not set.
+ */
+ public String getName() {
+ return name;
+ }
+
+ /**
+ * Bean property setter: <property>name</property>.
+ *
+ * <p>
+ * Required. The name of the tag.
+ *
+ * @param name The new value for the <property>name</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Tag setName(String name) {
+ this.name = name;
+ return this;
+ }
+
+ /**
+ * Synonym for {@link #setName(String)}.
+ *
+ * @param name The new value for the <property>name</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Tag name(String name) {
+ return setName(name);
+ }
+
+ /**
+ * Bean property getter: <property>description</property>.
+ *
+ * <p>
+ * A short description for the tag.
+ *
+ * <p>
+ * <a class="doclink" href="https://help.github.com/articles/github-flavored-markdown">GFM syntax</a> can be used
+ * for rich text representation.
+ *
+ * @return
+ * The value of the <property>description</property> property on this bean, or <jk>null</jk> if it is not set.
+ */
+ public String getDescription() {
+ return description;
+ }
+
+ /**
+ * Bean property setter: <property>description</property>.
+ *
+ * <p>
+ * A short description for the tag.
+ *
+ * <p>
+ * <a class="doclink" href="https://help.github.com/articles/github-flavored-markdown">GFM syntax</a> can be used
+ * for rich text representation.
+ *
+ * @param description The new value for the <property>description</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Tag setDescription(String description) {
+ this.description = description;
+ return this;
+ }
+
+ /**
+ * Synonym for {@link #setDescription(String)}.
+ *
+ * @param description The new value for the <property>description</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Tag description(String description) {
+ return setDescription(description);
+ }
+
+ /**
+ * Bean property getter: <property>externalDocs</property>.
+ *
+ * <p>
+ * Additional external documentation for this tag.
+ *
+ * @return
+ * The value of the <property>externalDocs</property> property on this bean, or <jk>null</jk> if it is not set.
+ */
+ public ExternalDocumentation getExternalDocs() {
+ return externalDocs;
+ }
+
+ /**
+ * Bean property setter: <property>externalDocs</property>.
+ *
+ * <p>
+ * Additional external documentation for this tag.
+ *
+ * @param externalDocs The new value for the <property>externalDocs</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Tag setExternalDocs(ExternalDocumentation externalDocs) {
+ this.externalDocs = externalDocs;
+ return this;
+ }
+
+ /**
+ * Synonym for {@link #setExternalDocs(ExternalDocumentation)}.
+ *
+ * @param externalDocs The new value for the <property>externalDocs</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Tag externalDocs(ExternalDocumentation externalDocs) {
+ return setExternalDocs(externalDocs);
+ }
+}
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/75b0d8ee/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/Xml.java
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/Xml.java b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/Xml.java
new file mode 100644
index 0000000..39b7e53
--- /dev/null
+++ b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/Xml.java
@@ -0,0 +1,264 @@
+// ***************************************************************************************************************************
+// * 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.dto.swagger;
+
+import org.apache.juneau.annotation.*;
+
+/**
+ * A metadata object that allows for more fine-tuned XML model definitions.
+ *
+ * <p>
+ * When using arrays, XML element names are not inferred (for singular/plural forms) and the name property should be
+ * used to add that information.
+ *
+ * <h6 class='topic'>Additional Information</h6>
+ * <ul class='doctree'>
+ * <li class='link'>
+ * <a class='doclink' href='../../../../../overview-summary.html#DTOs'>Juneau Data Transfer Objects
+ * (org.apache.juneau.dto)</a>
+ * <ul>
+ * <li class='sublink'>
+ * <a class='doclink' href='../../../../../overview-summary.html#DTOs.Swagger'>Swagger</a>
+ * </ul>
+ * </li>
+ * <li class='jp'>
+ * <a class='doclink' href='package-summary.html#TOC'>org.apache.juneau.dto.swagger</a>
+ * </li>
+ * </ul>
+ */
+@Bean(properties="name,namespace,prefix,attribute,wrapped")
+@SuppressWarnings("hiding")
+public class Xml extends SwaggerElement {
+
+ private String name;
+ private String namespace;
+ private String prefix;
+ private Boolean attribute;
+ private Boolean wrapped;
+
+ /**
+ * Bean property getter: <property>name</property>.
+ *
+ * <p>
+ * Replaces the name of the element/attribute used for the described schema property.
+ *
+ * <p>
+ * When defined within the Items Object (<code>items</code>), it will affect the name of the individual XML elements
+ * within the list.
+ * When defined alongside <code>type</code> being array (outside the <code>items</code>), it will affect the
+ * wrapping element and only if wrapped is <jk>true</jk>.
+ * If wrapped is <jk>false</jk>, it will be ignored.
+ *
+ * @return The value of the <property>name</property> property on this bean, or <jk>null</jk> if it is not set.
+ */
+ public String getName() {
+ return name;
+ }
+
+ /**
+ * Bean property setter: <property>name</property>.
+ *
+ * <p>
+ * Replaces the name of the element/attribute used for the described schema property.
+ *
+ * <p>
+ * When defined within the Items Object (<code>items</code>), it will affect the name of the individual XML elements
+ * within the list.
+ * When defined alongside <code>type</code> being array (outside the <code>items</code>), it will affect the
+ * wrapping element and only if wrapped is <jk>true</jk>.
+ * If wrapped is <jk>false</jk>, it will be ignored.
+ *
+ * @param name The new value for the <property>name</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Xml setName(String name) {
+ this.name = name;
+ return this;
+ }
+
+ /**
+ * Synonym for {@link #setName(String)}.
+ *
+ * @param name The new value for the <property>name</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Xml name(String name) {
+ return setName(name);
+ }
+
+ /**
+ * Bean property getter: <property>namespace</property>.
+ *
+ * <p>
+ * The URL of the namespace definition. Value SHOULD be in the form of a URL.
+ *
+ * @return The value of the <property>namespace</property> property on this bean, or <jk>null</jk> if it is not set.
+ */
+ public String getNamespace() {
+ return namespace;
+ }
+
+ /**
+ * Bean property setter: <property>namespace</property>.
+ *
+ * <p>
+ * The URL of the namespace definition. Value SHOULD be in the form of a URL.
+ *
+ * @param namespace The new value for the <property>namespace</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Xml setNamespace(String namespace) {
+ this.namespace = namespace;
+ return this;
+ }
+
+ /**
+ * Synonym for {@link #setNamespace(String)}.
+ *
+ * @param namespace The new value for the <property>namespace</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Xml namespace(String namespace) {
+ return setNamespace(namespace);
+ }
+
+ /**
+ * Bean property getter: <property>prefix</property>.
+ *
+ * <p>
+ * The prefix to be used for the name.
+ *
+ * @return The value of the <property>prefix</property> property on this bean, or <jk>null</jk> if it is not set.
+ */
+ public String getPrefix() {
+ return prefix;
+ }
+
+ /**
+ * Bean property setter: <property>prefix</property>.
+ *
+ * <p>
+ * The prefix to be used for the name.
+ *
+ * @param prefix The new value for the <property>prefix</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Xml setPrefix(String prefix) {
+ this.prefix = prefix;
+ return this;
+ }
+
+ /**
+ * Synonym for {@link #setPrefix(String)}.
+ *
+ * @param prefix The new value for the <property>prefix</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Xml prefix(String prefix) {
+ return setPrefix(prefix);
+ }
+
+ /**
+ * Bean property getter: <property>attribute</property>.
+ *
+ * <p>
+ * Declares whether the property definition translates to an attribute instead of an element.
+ *
+ * <p>
+ * Default value is <jk>false</jk>.
+ *
+ * @return The value of the <property>attribute</property> property on this bean, or <jk>null</jk> if it is not set.
+ */
+ public Boolean getAttribute() {
+ return attribute;
+ }
+
+ /**
+ * Bean property setter: <property>attribute</property>.
+ *
+ * <p>
+ * Declares whether the property definition translates to an attribute instead of an element.
+ *
+ * <p>
+ * Default value is <jk>false</jk>.
+ *
+ * @param attribute The new value for the <property>attribute</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Xml setAttribute(Boolean attribute) {
+ this.attribute = attribute;
+ return this;
+ }
+
+ /**
+ * Synonym for {@link #setAttribute(Boolean)}.
+ *
+ * @param attribute The new value for the <property>attribute</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Xml attribute(Boolean attribute) {
+ return setAttribute(attribute);
+ }
+
+ /**
+ * Bean property getter: <property>wrapped</property>.
+ *
+ * <p>
+ * MAY be used only for an array definition.
+ *
+ * <p>
+ * Signifies whether the array is wrapped (for example,
+ * <code><books><book/><book/><books></code>) or unwrapped
+ * (<code><book/><book/></code>).
+ * Default value is <jk>false</jk>.
+ * The definition takes effect only when defined alongside <code>type</code> being <code>array</code>
+ * (outside the <code>items</code>).
+ *
+ * @return The value of the <property>wrapped</property> property on this bean, or <jk>null</jk> if it is not set.
+ */
+ public Boolean getWrapped() {
+ return wrapped;
+ }
+
+ /**
+ * Bean property setter: <property>wrapped</property>.
+ *
+ * <p>
+ * MAY be used only for an array definition.
+ *
+ * <p>
+ * Signifies whether the array is wrapped (for example,
+ * <code><books><book/><book/><books></code>) or unwrapped
+ * (<code><book/><book/></code>).
+ * Default value is <jk>false</jk>.
+ * The definition takes effect only when defined alongside <code>type</code> being <code>array</code>
+ * (outside the <code>items</code>).
+ *
+ * @param wrapped The new value for the <property>wrapped</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Xml setWrapped(Boolean wrapped) {
+ this.wrapped = wrapped;
+ return this;
+ }
+
+ /**
+ * Synonym for {@link #setWrapped(Boolean)}.
+ *
+ * @param wrapped The new value for the <property>wrapped</property> property on this bean.
+ * @return This object (for method chaining).
+ */
+ public Xml wrapped(Boolean wrapped) {
+ return setWrapped(wrapped);
+ }
+}
http://git-wip-us.apache.org/repos/asf/incubator-juneau/blob/75b0d8ee/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/package.html
----------------------------------------------------------------------
diff --git a/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/package.html b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/package.html
new file mode 100644
index 0000000..8966843
--- /dev/null
+++ b/juneau-core/juneau-dto/src/main/java/org/apache/juneau/dto/swagger/package.html
@@ -0,0 +1,214 @@
+<!DOCTYPE HTML>
+<!--
+/***************************************************************************************************************************
+ * 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.
+ *
+ ***************************************************************************************************************************/
+-->
+<html>
+<head>
+ <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
+ <style type="text/css">
+ /* For viewing in Page Designer */
+ @IMPORT url("../../../../../../../javadoc.css");
+
+ /* For viewing in REST interface */
+ @IMPORT url("../htdocs/javadoc.css");
+ body {
+ margin: 20px;
+ }
+ </style>
+ <script>
+ /* Replace all @code and @link tags. */
+ window.onload = function() {
+ document.body.innerHTML = document.body.innerHTML.replace(/\{\@code ([^\}]+)\}/g, '<code>$1</code>');
+ document.body.innerHTML = document.body.innerHTML.replace(/\{\@link (([^\}]+)\.)?([^\.\}]+)\}/g, '<code>$3</code>');
+ }
+ </script>
+</head>
+<body>
+<p>Swagger Data Transfer Objects</p>
+<script>
+ function toggle(x) {
+ var div = x.nextSibling;
+ while (div != null && div.nodeType != 1)
+ div = div.nextSibling;
+ if (div != null) {
+ var d = div.style.display;
+ if (d == 'block' || d == '') {
+ div.style.display = 'none';
+ x.className += " closed";
+ } else {
+ div.style.display = 'block';
+ x.className = x.className.replace(/(?:^|\s)closed(?!\S)/g , '' );
+ }
+ }
+ }
+</script>
+<a id='TOC'></a><h5 class='toc'>Table of Contents</h5>
+<ol class='toc'>
+ <li><p><a class='doclink' href='#Overview'>Overview</a></p>
+ <ol>
+ <li><p><a class='doclink' href='#Serialize'>Generating Swagger Docs</a></p>
+ <li><p><a class='doclink' href='#Parse'>Parsing Swagger Docs</a></p>
+ </ol>
+</ol>
+
+
+<!-- ======================================================================================================== -->
+<a id="Overview"></a>
+<h2 class='topic' onclick='toggle(this)'>1 - Overview</h2>
+<div class='topic'>
+ <p>
+ Juneau supports generation and consumption of Swagger 2.0 documents and fragments through the use of DTOs
+ (Data Transfer Objects).
+ <br>It uses existing support for serializing and parsing POJOs to and from JSON to define these objects.
+ </p>
+
+ <!-- ======================================================================================================== -->
+ <a id="Serialize"></a>
+ <h3 class='topic' onclick='toggle(this)'>1.1 - Generating Swagger Docs</h3>
+ <div class='topic'>
+ <p>
+ The following is an example Swagger document from the <a href="http://petstore.swagger.io/">Swagger website</a>.
+ </p>
+ <p class='bcode'>
+ {
+ <jf>"swagger"</jf>: <js>"2.0"</js>,
+ <jf>"info"</jf>: {
+ <jf>"title"</jf>: <js>"Swagger Petstore"</js>,
+ <jf>"description"</jf>: <js>"This is a sample server Petstore server."</js>,
+ <jf>"version"</jf>: <js>"1.0.0"</js>,
+ <jf>"termsOfService"</jf>: <js>"http://swagger.io/terms/"</js>,
+ <jf>"contact"</jf>: {
+ <jf>"email"</jf>: <js>"apiteam@swagger.io"</js>
+ },
+ <jf>"license"</jf>: {
+ <jf>"name"</jf>: <js>"Apache 2.0"</js>,
+ <jf>"url"</jf>: <js>"http://www.apache.org/licenses/LICENSE-2.0.html"</js>
+ }
+ },
+ <jf>"host"</jf>: <js>"petstore.swagger.io"</js>,
+ <jf>"basePath"</jf>: <js>"/v2"</js>,
+ <jf>"tags"</jf>: [
+ {
+ <jf>"name"</jf>: <js>"pet"</js>,
+ <jf>"description"</jf>: <js>"Everything about your Pets"</js>,
+ <jf>"externalDocs"</jf>: {
+ <jf>"description"</jf>: <js>"Find out more"</js>,
+ <jf>"url"</jf>: <js>"http://swagger.io"</js>
+ }
+ }
+ ],
+ <jf>"schemes"</jf>: [
+ <js>"http"</js>
+ ],
+ <jf>"paths"</jf>: {
+ <jf>"/pet"</jf>: {
+ <jf>"post"</jf>: {
+ <jf>"tags"</jf>: [
+ <js>"pet"</js>
+ ],
+ <jf>"summary"</jf>: <js>"Add a new pet to the store"</js>,
+ <jf>"description"</jf>: <js>""</js>,
+ <jf>"operationId"</jf>: <js>"addPet"</js>,
+ <jf>"consumes"</jf>: [
+ <js>"application/json"</js>,
+ <js>"text/xml"</js>
+ ],
+ <jf>"produces"</jf>: [
+ <js>"application/json"</js>,
+ <js>"text/xml"</js>
+ ],
+ <jf>"parameters"</jf>: [
+ {
+ <jf>"in"</jf>: <js>"body"</js>,
+ <jf>"name"</jf>: <js>"body"</js>,
+ <jf>"description"</jf>: <js>"Pet object that needs to be added to the store"</js>,
+ <jf>"required"</jf>: <jk>true</jk>
+ }
+ ],
+ <jf>"responses"</jf>: {
+ <jf>"405"</jf>: {
+ <jf>"description"</jf>: <js>"Invalid input"</js>
+ }
+ }
+ }
+ }
+ },
+ }
+ </p>
+ <p>
+ This document can be generated by the following Java code:
+ </p>
+ <p class='bcode'>
+ <jk>static import</jk> org.apache.juneau.dto.swagger.SwaggerBuilder.*;
+
+ Swagger swagger = <jsm>swagger</jsm>()
+ .swagger(<js>"2.0"</js>)
+ .info(
+ <jsm>info</jsm>(<js>"Swagger Petstore"</js>, <js>"1.0.0"</js>)
+ .description(<js>"This is a sample server Petstore server."</js>)
+ .termsOfService(<js>"http://swagger.io/terms/"</js>)
+ .contact(
+ <jsm>contact</jsm>().email(<js>"apiteam@swagger.io"</js>)
+ )
+ .license(
+ <jsm>license</jsm>(<js>"Apache 2.0"</js>)
+ .url(<js>"http://www.apache.org/licenses/LICENSE-2.0.html"</js>)
+ )
+ )
+ .host(<js>"petstore.swagger.io"</js>)
+ .basePath(<js>"/v2"</js>)
+ .tags(
+ <jsm>tag</jsm>(<js>"pet"</js>).description(<js>"Everything about your Pets"</js>)
+ .externalDocs(
+ <jsm>externalDocumentation</jsm>(<js>"http://swagger.io"</js>, <js>"http://swagger.io"</js>)
+ )
+ )
+ .schemes(<js>"http"</js>)
+ .path(<js>"/pet"</js>, <js>"post"</js>,
+ <jsm>operation</jsm>()
+ .tags(<js>"pet"</js>)
+ .summary(<js>"Add a new pet to the store"</js>)
+ .description(<js>""</js>)
+ .operationId(<js>"addPet"</js>)
+ .consumes(MediaType.<jsf>JSON</jsf>, MediaType.<jsf>XML</jsf>)
+ .produces(MediaType.<jsf>JSON</jsf>, MediaType.<jsf>XML</jsf>)
+ .parameters(
+ <jsm>parameterInfo</jsm>(<js>"body"</js>, <js>"body"</js>)
+ .description(<js>"Pet object that needs to be added to the store"</js>)
+ .required(<jk>true</jk>)
+ )
+ .response(405, <jsm>responseInfo</jsm>(<js>"Invalid input"</js>))
+ );
+
+ String swaggerJson = JsonSerializer.<jsf>DEFAULT_READABLE</jsf>.serialize(swagger);
+ </p>
+ </div>
+
+ <!-- ======================================================================================================== -->
+ <a id="Parse"></a>
+ <h3 class='topic' onclick='toggle(this)'>1.2 - Parsing Swagger Docs</h3>
+ <div class='topic'>
+ <p>
+ Swagger docs can be parsed back into Swagger beans using the following code:
+ </p>
+ <p class='bcode'>
+ Swagger swagger = JsonParser.<jsf>DEFAULT</jsf>.parse(swaggerJson, Swagger.<jk>class</jk>);
+ </p>
+ </div>
+
+</div>
+
+</body>
+</html>