Support more metadata in SwaggerConf (#58)

Adding more Open API sections to the plugin configuration.

(replacing PR#53)

Co-authored-by: Wanno Drijfhout <[email protected]>

Author: langecode

src/main/java/io/openapitools/swagger/OutputFormat.java

@@ -1,12 +1,15 @@
 package io.openapitools.swagger;
 
+import java.io.File;
+import java.io.IOException;
+
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.databind.SerializationFeature;
+import io.openapitools.swagger.config.SwaggerServerVariable;
 import io.swagger.v3.core.util.Json;
 import io.swagger.v3.core.util.Yaml;
 import io.swagger.v3.oas.models.OpenAPI;
-import java.io.File;
-import java.io.IOException;
+import io.swagger.v3.oas.models.servers.ServerVariable;
 
 /**
  * Supported output formats.
@@ -42,6 +45,7 @@ static class JSONWriter implements SwaggerWriter {
         @Override
         public void write(OpenAPI swagger, File file, boolean prettyPrint) throws IOException {
             ObjectMapper mapper = Json.mapper();
+            mapper.addMixIn(ServerVariable.class, SwaggerServerVariable.ServerVariableMixin.class);
             if (prettyPrint) {
                 mapper.enable(SerializationFeature.INDENT_OUTPUT);
             }
@@ -56,7 +60,9 @@ static class YAMLWriter implements SwaggerWriter {
 
         @Override
         public void write(OpenAPI swagger, File file, boolean prettyPrint) throws IOException {
-            Yaml.mapper().writeValue(file, swagger);
+            ObjectMapper mapper = Yaml.mapper();
+            mapper.addMixIn(ServerVariable.class, SwaggerServerVariable.ServerVariableMixin.class);
+            mapper.writeValue(file, swagger);
         }
     }
 }

src/main/java/io/openapitools/swagger/config/SwaggerComponents.java

@@ -0,0 +1,29 @@
+package io.openapitools.swagger.config;
+
+import java.util.Map;
+
+import org.apache.maven.plugins.annotations.Parameter;
+
+import io.swagger.v3.oas.models.Components;
+
+public class SwaggerComponents {
+
+    /**
+     * Security schemes (under Comtonents)
+     */
+    @Parameter
+    private Map<String,SwaggerSecurityScheme> securitySchemes;
+
+    // TODO: implement schemas, responses, ... from
+    // https://github.com/OAI/OpenAPI-Specification/blob/3.0.1/versions/3.0.1.md#componentsObject
+
+    public Components createComponentsModel() {
+        Components components = new Components();
+
+        if (securitySchemes != null && !securitySchemes.isEmpty()) {
+            securitySchemes.entrySet().forEach(s -> components.addSecuritySchemes(s.getKey(), s.getValue().createSecuritySchemaModel()));
+        }
+
+        return components;
+    }
+}

src/main/java/io/openapitools/swagger/config/SwaggerConfig.java

@@ -1,44 +1,88 @@
 package io.openapitools.swagger.config;
 
+import io.swagger.v3.oas.annotations.ExternalDocumentation;
+import io.swagger.v3.oas.annotations.Parameters;
 import io.swagger.v3.oas.models.OpenAPI;
 import io.swagger.v3.oas.models.info.Info;
 import java.io.File;
 import java.io.IOException;
 import java.nio.file.Files;
-import java.util.Arrays;
 import java.util.Collections;
 import java.util.List;
+import java.util.Map;
 import java.util.stream.Collectors;
 import org.apache.maven.plugins.annotations.Parameter;
 
 /**
- * Configuring Swagger in compliance with the way the com.github.kongchen Swagger plugin does it.
+ * Configuring Swagger in compliance with the way the com.github.kongchen
+ * Swagger plugin does it.
  */
 public class SwaggerConfig {
 
     /**
-     * List of servers for the endpoint.
+     * REQUIRED. Provides metadata about the API. The metadata MAY be used by
+     * tooling as required.
+     * 
+     * This might be overridden by ReaderListener or SwaggerDefinition annotation.
+     */
+    @Parameter
+    private SwaggerInfo info;
+
+    /**
+     * Convenience for reading the informational description from file instead of
+     * embedding it.
+     */
+    @Parameter
+    private File descriptionFile;
+
+    /**
+     * An array of Server Objects, which provide connectivity information to a
+     * target server. If the servers property is not provided, or is an empty array,
+     * the default value would be a Server Object with a url value of /.
      */
     @Parameter
     private List<SwaggerServer> servers = Collections.emptyList();
 
     /**
-     * Providing the OpenAPI information description. This might be overridden by ReaderListener or SwaggerDefinition annotation.
+     * An element to hold various schemas for the specification.
      */
     @Parameter
-    private SwaggerInfo info;
+    private SwaggerComponents components;
 
     /**
-     * Convenience for reading the informational description from file instead of embedding it.
+     * A declaration of which security mechanisms can be used across the API. The
+     * list of values includes alternative security requirement objects that can be
+     * used. Only one of the security requirement objects need to be satisfied to
+     * authorize a request. Individual operations can override this definition.
      */
     @Parameter
-    private File descriptionFile;
+    private List<SwaggerSecurityRequirement> securityRequirements = Collections.emptyList();;
+
+    /**
+     * A list of tags used by the specification with additional metadata. 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 Operation Object 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.
+     */
+    @Parameter
+    private List<SwaggerTag> tags = Collections.emptyList();;
+
+    /**
+     * Additional external documentation.
+     */
+    @Parameter
+    private SwaggerExternalDoc externalDoc;
+
+    /**
+     * Providing extension attributes to the OpenAPI spec.
+     */
+    @Parameter
+    private Map<String, Object> extensions = Collections.emptyMap();
 
     public OpenAPI createSwaggerModel() {
         OpenAPI spec = new OpenAPI();
 
-        servers.forEach(s -> spec.addServersItem(s.createServerModel()));
-
         if (info != null) {
             spec.setInfo(info.createInfoModel());
         }
@@ -48,12 +92,26 @@ public OpenAPI createSwaggerModel() {
                 spec.setInfo(new Info());
             }
             try {
-                spec.getInfo().setDescription(Files.readAllLines(descriptionFile.toPath()).stream().collect(Collectors.joining("\n")));
+                spec.getInfo().setDescription(
+                        Files.readAllLines(descriptionFile.toPath()).stream().collect(Collectors.joining("\n")));
             } catch (IOException e) {
                 throw new RuntimeException("Unable to read descriptor file " + descriptionFile, e);
             }
         }
 
+        if (components != null) {
+            spec.setComponents(components.createComponentsModel());
+        }
+
+        if (externalDoc != null) {
+            spec.setExternalDocs(externalDoc.createExternalDocModel());
+        }
+
+        spec.setExtensions(extensions);
+        servers.forEach(s -> spec.addServersItem(s.createServerModel()));
+        securityRequirements.forEach(s -> spec.addSecurityItem(s.createSecurityModel()));
+        tags.forEach(t -> spec.addTagsItem(t.createTagModel()));
+
         return spec;
     }
 }

src/main/java/io/openapitools/swagger/config/SwaggerContact.java

@@ -1,22 +1,38 @@
 package io.openapitools.swagger.config;
 
 import io.swagger.v3.oas.models.info.Contact;
+
+import java.util.Collections;
+import java.util.Map;
+
 import org.apache.maven.plugins.annotations.Parameter;
 
 /**
  * Configuring Swagger contact properties.
  */
 public class SwaggerContact {
 
+    /**
+     * The identifying name of the contact person/organization.
+     */
     @Parameter
     private String name;
 
+    /**
+     * The URL pointing to the contact information. MUST be in the format of a URL.
+     */
     @Parameter
     private String url;
 
+    /**
+     * The email address of the contact person/organization. MUST be in the format of an email address.
+     */
     @Parameter
     private String email;
 
+    @Parameter
+    private Map<String, Object> extensions = Collections.emptyMap();
+
     public Contact createContactModel() {
         Contact contact = new Contact();
 
@@ -32,6 +48,8 @@ public Contact createContactModel() {
             contact.setEmail(email);
         }
 
+        contact.setExtensions(extensions);
+
         return contact;
     }
 }

src/main/java/io/openapitools/swagger/config/SwaggerExternalDoc.java

@@ -0,0 +1,45 @@
+package io.openapitools.swagger.config;
+
+import java.util.Collections;
+import java.util.Map;
+
+import org.apache.maven.plugins.annotations.Parameter;
+
+import io.swagger.v3.oas.models.ExternalDocumentation;
+
+public class SwaggerExternalDoc {
+
+    /**
+     * A short description of the target documentation. CommonMark syntax MAY be
+     * used for rich text representation.
+     */
+    @Parameter
+    private String description;
+
+    /**
+     * REQUIRED. The URL for the target documentation. Value MUST be in the format
+     * of a URL.
+     */
+    @Parameter(required = true)
+    private String url;
+
+    @Parameter
+    private Map<String, Object> extensions = Collections.emptyMap();
+
+    public ExternalDocumentation createExternalDocModel() {
+        ExternalDocumentation externalDoc = new ExternalDocumentation();
+
+        if (description != null) {
+            externalDoc.setDescription(description);
+        }
+
+        if (url != null) {
+            externalDoc.setUrl(url);
+        }
+
+        externalDoc.setExtensions(extensions);
+
+        return externalDoc;
+    }
+
+}

src/main/java/io/openapitools/swagger/config/SwaggerFlows.java

@@ -0,0 +1,106 @@
+package io.openapitools.swagger.config;
+
+import java.util.Collections;
+import java.util.Map;
+
+import io.swagger.v3.oas.annotations.Parameter;
+import io.swagger.v3.oas.models.security.OAuthFlow;
+import io.swagger.v3.oas.models.security.OAuthFlows;
+import io.swagger.v3.oas.models.security.Scopes;
+
+public class SwaggerFlows {
+
+    /**
+     * Configuration for the OAuth Implicit flow
+     */
+    @Parameter
+    private Entry implicit;
+
+    /**
+     * Configuration for the OAuth Resource Owner Password flow
+     */
+    @Parameter
+    private Entry password;
+
+    /**
+     * Configuration for the OAuth Client Credentials flow. Previously called
+     * application in OpenAPI 2.0.
+     */
+    @Parameter
+    private Entry clientCredentials;
+
+    /**
+     * Configuration for the OAuth Authorization Code flow. Previously called
+     * accessCode in OpenAPI 2.0.
+     */
+    @Parameter
+    private Entry authorizationCode;
+
+    @Parameter
+    private Map<String, Object> extensions = Collections.emptyMap();
+
+    public OAuthFlows createOAuthFlowsModel() {
+        OAuthFlows flows = new OAuthFlows();
+        if (implicit != null) {
+            flows.setImplicit(implicit.toOAuthFlowModel());
+        }
+        if (password != null) {
+            flows.setPassword(password.toOAuthFlowModel());
+        }
+        if (clientCredentials != null) {
+            flows.setClientCredentials(clientCredentials.toOAuthFlowModel());
+        }
+        if (authorizationCode != null) {
+            flows.setAuthorizationCode(authorizationCode.toOAuthFlowModel());
+        }
+        flows.setExtensions(extensions);
+        return flows;
+    }
+
+    public static class Entry {
+        /**
+         * For implicit/authorizationCode flows: REQUIRED. The authorization URL to be used for this flow. This MUST be in the form of a URL.
+         */
+        @Parameter
+        private String authorizationUrl;
+
+        /**
+         * For password/clientCredentials/AuthorizationCode flows: REQUIRED. The token URL to be used for this flow. This MUST be in the form of a URL.
+         */
+        @Parameter
+        private String tokenUrl;
+
+        /**
+         * The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL.
+         */
+        @Parameter
+        private String refreshUrl;
+
+        /**
+         * REQUIRED. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it.
+         */
+        @Parameter(required = true)
+        private Map<String, String> scopes = Collections.emptyMap();
+
+        @Parameter
+        private Map<String, Object> extensions = Collections.emptyMap();
+
+        public OAuthFlow toOAuthFlowModel() {
+            OAuthFlow flow = new OAuthFlow();
+
+            flow.setAuthorizationUrl(authorizationUrl);
+            flow.setTokenUrl(tokenUrl);
+            flow.setRefreshUrl(refreshUrl);
+            if (scopes != null && !scopes.isEmpty()) {
+                Scopes ss = new Scopes();
+                scopes.entrySet().forEach(s -> ss.addString(s.getKey(), s.getValue()));
+                flow.setScopes(ss);
+            }
+
+            if (extensions != null && !extensions.isEmpty()) {
+                flow.setExtensions(extensions);
+            }
+            return flow;
+        }
+    }
+}