Update restdocs-api-spec to 0.8.0

support configuring description & tag descriptions from pom.xml

Author: cnsgithub

pom.xml

@@ -6,7 +6,7 @@
 
   <groupId>com.github.cnsgithub.restdocs-spec</groupId>
   <artifactId>restdocs-spec</artifactId>
-  <version>0.10.3-cns</version>
+  <version>0.10.4-cns</version>
   <packaging>pom</packaging>
 
   <name>${project.groupId}:${project.artifactId}</name>
@@ -72,7 +72,7 @@
     <maven.compiler.target>1.8</maven.compiler.target>
     <maven.version>3.3.1</maven.version>
     <maven-plugin-tools.version>3.5.2</maven-plugin-tools.version>
-    <restdocs-api-spec.version>0.5.0</restdocs-api-spec.version>
+    <restdocs-api-spec.version>0.8.0</restdocs-api-spec.version>
     <junit.version>5.2.0</junit.version>
     <assertj.version>3.11.0</assertj.version>
     <mockito.version>2.21.0</mockito.version>

restdocs-spec-generator/pom.xml

@@ -6,7 +6,7 @@
   <parent>
     <groupId>com.github.cnsgithub.restdocs-spec</groupId>
     <artifactId>restdocs-spec</artifactId>
-    <version>0.10.3-cns</version>
+    <version>0.10.4-cns</version>
   </parent>
 
   <artifactId>restdocs-spec-generator</artifactId>

restdocs-spec-generator/src/main/java/com/berkleytechnologyservices/restdocs/spec/ApiDetails.java

@@ -1,7 +1,9 @@
 package com.berkleytechnologyservices.restdocs.spec;
 
 import java.util.Collections;
+import java.util.HashMap;
 import java.util.List;
+import java.util.Map;
 
 public class ApiDetails {
 
@@ -13,11 +15,13 @@ public class ApiDetails {
 
   private String name;
   private String version;
+  private String description;
   private String host;
   private String basePath;
   private List<String> schemes;
   private SpecificationFormat format;
   private AuthConfig authConfig;
+  private Map<String, String> tagDescriptions;
 
   public ApiDetails() {
     this.name = DEFAULT_NAME;
@@ -27,6 +31,7 @@ public ApiDetails() {
     this.schemes = DEFAULT_SCHEMES;
     this.format = DEFAULT_FORMAT;
     this.authConfig = new AuthConfig();
+    this.tagDescriptions = Collections.emptyMap();
   }
 
   public String getName() {
@@ -47,6 +52,15 @@ public ApiDetails version(String version) {
     return this;
   }
 
+  public String getDescription() {
+    return description;
+  }
+
+  public ApiDetails description(String description){
+    this.description = description;
+    return this;
+  }
+
   public String getHost() {
     return host;
   }
@@ -91,4 +105,13 @@ public ApiDetails authConfig(AuthConfig authConfig) {
     this.authConfig = authConfig != null ? authConfig : new AuthConfig();
     return this;
   }
+
+  public Map<String, String> getTagDescriptions() {
+    return tagDescriptions;
+  }
+
+  public ApiDetails tagDescriptions(Map<String, String> tagDescriptions) {
+    this.tagDescriptions = tagDescriptions;
+    return this;
+  }
 }

restdocs-spec-generator/src/main/java/com/berkleytechnologyservices/restdocs/spec/generator/openapi_v2/OpenApi20SpecificationGenerator.java

@@ -11,6 +11,7 @@
 import com.epages.restdocs.apispec.openapi2.OpenApi20Generator;
 
 import javax.inject.Named;
+import java.util.HashMap;
 import java.util.List;
 import java.util.stream.Collectors;
 
@@ -40,6 +41,8 @@ public String generate(ApiDetails details, List<ResourceModel> models) {
         details.getHost(),
         details.getSchemes(),
         details.getName(),
+        details.getDescription(),
+        details.getTagDescriptions(),
         details.getVersion(),
         SpecificationGeneratorUtils.createOauth2Configuration(details.getAuthConfig()),
         details.getFormat().name().toLowerCase()

restdocs-spec-generator/src/main/java/com/berkleytechnologyservices/restdocs/spec/generator/openapi_v3/OpenApi30SpecificationGenerator.java

@@ -14,9 +14,7 @@
 import javax.inject.Named;
 import java.net.MalformedURLException;
 import java.net.URL;
-import java.util.ArrayList;
-import java.util.Arrays;
-import java.util.List;
+import java.util.*;
 import java.util.stream.Collectors;
 
 @Named
@@ -52,6 +50,8 @@ public String generate(ApiDetails details, List<ResourceModel> models) {
             models,
             servers,
             details.getName(),
+            details.getDescription(),
+            details.getTagDescriptions(),
             details.getVersion(),
             SpecificationGeneratorUtils.createOauth2Configuration(details.getAuthConfig()),
             details.getFormat().name().toLowerCase()

restdocs-spec-generator/src/test/resources/mock-specs/default-settings-openapi3.yml

@@ -4,6 +4,7 @@ info:
   version: 1.0.0
 servers:
 - url: http://localhost
+tags: []
 paths:
   /book/{id}:
     get:
@@ -17,6 +18,8 @@ paths:
         in: path
         description: The unique identifier for the book.
         required: true
+        schema:
+          type: string
       responses:
         200:
           description: "200"

restdocs-spec-generator/src/test/resources/mock-specs/default-settings.yml

@@ -3,6 +3,7 @@ info:
   version: 1.0.0
   title: API Documentation
 host: localhost
+tags: []
 schemes:
 - http
 paths:

restdocs-spec-maven-plugin/pom.xml

@@ -8,7 +8,7 @@
   <parent>
     <groupId>com.github.cnsgithub.restdocs-spec</groupId>
     <artifactId>restdocs-spec</artifactId>
-    <version>0.10.3-cns</version>
+    <version>0.10.4-cns</version>
   </parent>
 
   <artifactId>restdocs-spec-maven-plugin</artifactId>

restdocs-spec-maven-plugin/src/main/java/com/berkleytechnologyservices/restdocs/mojo/GenerateMojo.java

@@ -21,6 +21,7 @@
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
+import java.util.Map;
 import java.util.stream.Collectors;
 
 /**
@@ -43,6 +44,12 @@ public class GenerateMojo extends AbstractMojo {
   @Parameter(defaultValue = "${project.version}", required = true)
   private String version;
 
+  /**
+   * Description of the API
+   */
+  @Parameter(defaultValue = "${project.description}", required = true)
+  private String description;
+
   /**
    * Host
    */
@@ -108,6 +115,12 @@ public class GenerateMojo extends AbstractMojo {
   @Parameter
   private AuthConfig oauth2 = new AuthConfig();
 
+  /**
+   *  Mapping of tag names to descriptions. These are populated into the top level. {@see https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#tag-object}  | no default - if not provided no tags created.
+   */
+  @Parameter
+  private Map<String, String> tagDescriptions;
+
   private final SnippetReader snippetReader;
   private final SpecificationGeneratorFactory specificationGeneratorFactory;
 
@@ -201,11 +214,13 @@ private ApiDetails createApiDetails(SpecificationOptions options) {
     return new ApiDetails()
         .name(name)
         .version(version)
+		.description(description)
         .host(host)
         .basePath(basePath)
         .schemes(schemes)
         .format(options.getFormat())
-        .authConfig(oauth2);
+        .authConfig(oauth2)
+        .tagDescriptions(tagDescriptions);
   }
 
   private List<SpecificationOptions> getAllSpecificationOptions() {