Automatically generate Swagger documentation

services/mac_manager/pom.xml

@@ -16,8 +16,21 @@
 
     <properties>
         <java.version>1.8</java.version>
+        <swagger.output.dir>${project.build.directory}/swagger</swagger.output.dir>
+        <swagger2markup.version>1.2.0</swagger2markup.version>
     </properties>
 
+    <repositories>
+        <repository>
+            <snapshots>
+                <enabled>false</enabled>
+            </snapshots>
+            <id>jcenter-releases</id>
+            <name>jcenter</name>
+            <url>https://jcenter.bintray.com</url>
+        </repository>
+    </repositories>
+
     <dependencies>
         <dependency>
             <groupId>org.springframework.boot</groupId>
@@ -71,6 +84,18 @@
                 </exclusion>
             </exclusions>
         </dependency>
+        <dependency>
+            <groupId>io.springfox</groupId>
+            <artifactId>springfox-swagger2</artifactId>
+            <version>2.6.1</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>io.github.swagger2markup</groupId>
+            <artifactId>swagger2markup-spring-restdocs-ext</artifactId>
+            <version>${swagger2markup.version}</version>
+            <scope>test</scope>
+        </dependency>
         <dependency>
             <groupId>com.futurewei.alcor.common</groupId>
             <artifactId>AlcorCommonLib</artifactId>
@@ -85,6 +110,15 @@
                 <groupId>org.springframework.boot</groupId>
                 <artifactId>spring-boot-maven-plugin</artifactId>
             </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-surefire-plugin</artifactId>
+                <configuration>
+                    <systemPropertyVariables>
+                        <io.springfox.staticdocs.outputDir>${swagger.output.dir}</io.springfox.staticdocs.outputDir>
+                    </systemPropertyVariables>
+                </configuration>
+            </plugin>
         </plugins>
     </build>
 

services/mac_manager/src/test/java/com/futurewei/alcor/macmanager/swagger/SwaggerConfig.java

@@ -0,0 +1,52 @@
+/*
+Copyright 2019 The Alcor Authors.
+
+Licensed 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 com.futurewei.alcor.macmanager.swagger;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+import springfox.documentation.builders.PathSelectors;
+import springfox.documentation.builders.RequestHandlerSelectors;
+import springfox.documentation.service.ApiInfo;
+import springfox.documentation.spi.DocumentationType;
+import springfox.documentation.spring.web.plugins.Docket;
+import springfox.documentation.builders.ApiInfoBuilder;
+import springfox.documentation.swagger2.annotations.EnableSwagger2;
+
+@Configuration
+@EnableSwagger2
+public class SwaggerConfig{
+    @Bean
+    public Docket api(){
+        return new Docket(DocumentationType.SWAGGER_2)
+            .apiInfo(apiInfo())
+            .select()
+            .apis(RequestHandlerSelectors.any())
+            .paths(PathSelectors.regex("(?!/error).+"))
+            .paths(PathSelectors.regex("(?!/actuator).+"))
+            .build();
+    }
+
+    private ApiInfo apiInfo(){
+        return new ApiInfoBuilder()
+            .title("Virtual MAC Manager")
+            .description("Virtual MAC pool management")
+            .license("Apache 2.0")
+            .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
+            .build();
+    }
+}

services/mac_manager/src/test/java/com/futurewei/alcor/macmanager/swagger/SwaggerJsonTest.java

@@ -0,0 +1,79 @@
+/*
+Copyright 2019 The Alcor Authors.
+
+Licensed 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 com.futurewei.alcor.macmanager.swagger;
+
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
+
+import org.springframework.mock.web.MockHttpServletResponse;
+import org.springframework.beans.factory.annotation.Autowired;
+
+import org.springframework.test.web.servlet.MockMvc;
+import org.springframework.test.web.servlet.MvcResult;
+
+import org.springframework.http.MediaType;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.springframework.test.context.junit4.SpringRunner;
+import java.io.BufferedWriter;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Paths;
+
+import io.github.swagger2markup.Swagger2MarkupConverter;
+import io.github.swagger2markup.Swagger2MarkupProperties;
+import io.github.swagger2markup.Swagger2MarkupConfig;
+import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder;
+
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+import static org.springframework.test.web.servlet.result.MockMvcResultHandlers.print;
+
+@RunWith(SpringRunner.class)
+@SpringBootTest
+@AutoConfigureMockMvc
+public class SwaggerJsonTest{
+
+    @Autowired
+    private MockMvc mockMvc;
+
+    @Test
+    public void createSpringfoxSwaggerJson() throws Exception{
+        String outputDir = System.getProperty("io.springfox.staticdocs.outputDir");
+        MvcResult mvcResult = this.mockMvc.perform(get("/v2/api-docs")
+            .accept(MediaType.APPLICATION_JSON))
+            .andExpect(status().isOk())
+            .andReturn();
+
+        MockHttpServletResponse response = mvcResult.getResponse();
+        String swaggerJson = response.getContentAsString();
+        Files.createDirectories(Paths.get(outputDir));
+        try(BufferedWriter writer = Files.newBufferedWriter(Paths.get(outputDir, "swagger.json"), StandardCharsets.UTF_8)){
+            writer.write(swaggerJson);
+        }
+
+        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
+            .withGeneratedExamples()
+            .withInterDocumentCrossReferences()
+            .build();
+        Swagger2MarkupConverter.from(Paths.get(outputDir,"swagger.json"))
+            .withConfig(config)
+            .build()
+            .toFile(Paths.get(outputDir, "swagger"));
+    }
+
+}

services/private_ip_manager/pom.xml

@@ -16,8 +16,21 @@
 
     <properties>
         <java.version>1.8</java.version>
+        <swagger.output.dir>${project.build.directory}/swagger</swagger.output.dir>
+        <swagger2markup.version>1.2.0</swagger2markup.version>
     </properties>
 
+    <repositories>
+        <repository>
+            <snapshots>
+                <enabled>false</enabled>
+            </snapshots>
+            <id>jcenter-releases</id>
+            <name>jcenter</name>
+            <url>https://jcenter.bintray.com</url>
+        </repository>
+    </repositories>
+
     <dependencies>
         <dependency>
             <groupId>org.springframework.boot</groupId>
@@ -28,20 +41,25 @@
             <groupId>org.springframework.boot</groupId>
             <artifactId>spring-boot-starter-test</artifactId>
             <scope>test</scope>
-            <exclusions>
-                <exclusion>
-                    <groupId>org.junit.vintage</groupId>
-                    <artifactId>junit-vintage-engine</artifactId>
-                </exclusion>
-            </exclusions>
         </dependency>
 
         <dependency>
             <groupId>org.projectlombok</groupId>
             <artifactId>lombok</artifactId>
             <version>1.18.0</version>
         </dependency>
-
+        <dependency>
+            <groupId>io.springfox</groupId>
+            <artifactId>springfox-swagger2</artifactId>
+            <version>2.6.1</version>
+            <scope>test</scope>
+        </dependency>
+        <dependency>
+            <groupId>io.github.swagger2markup</groupId>
+            <artifactId>swagger2markup-spring-restdocs-ext</artifactId>
+            <version>${swagger2markup.version}</version>
+            <scope>test</scope>
+        </dependency>
         <dependency>
             <groupId>com.futurewei.alcor.common</groupId>
             <artifactId>AlcorCommonLib</artifactId>
@@ -66,7 +84,10 @@
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-surefire-plugin</artifactId>
                 <configuration>
-                    <skip>false</skip>
+                    <skip>true</skip>
+                    <systemPropertyVariables>
+                        <io.springfox.staticdocs.outputDir>${swagger.output.dir}</io.springfox.staticdocs.outputDir>
+                    </systemPropertyVariables>
                 </configuration>
             </plugin>
             <plugin>

services/private_ip_manager/src/test/java/com/futurewei/alcor/privateipmanager/swagger/SwaggerConfig.java

@@ -0,0 +1,52 @@
+/*
+Copyright 2019 The Alcor Authors.
+
+Licensed 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 com.futurewei.alcor.privateipmanager.swagger;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+
+import springfox.documentation.builders.PathSelectors;
+import springfox.documentation.builders.RequestHandlerSelectors;
+import springfox.documentation.service.ApiInfo;
+import springfox.documentation.spi.DocumentationType;
+import springfox.documentation.spring.web.plugins.Docket;
+import springfox.documentation.builders.ApiInfoBuilder;
+import springfox.documentation.swagger2.annotations.EnableSwagger2;
+
+@Configuration
+@EnableSwagger2
+public class SwaggerConfig{
+    @Bean
+    public Docket api(){
+        return new Docket(DocumentationType.SWAGGER_2)
+            .apiInfo(apiInfo())
+            .select()
+            .apis(RequestHandlerSelectors.any())
+            .paths(PathSelectors.regex("(?!/error).+"))
+            .paths(PathSelectors.regex("(?!/actuator).+"))
+            .build();
+    }
+
+    private ApiInfo apiInfo(){
+        return new ApiInfoBuilder()
+            .title("Private IP Manager")
+            .description("VPC Private IP lifecycle management(IPv4/6)")
+            .license("Apache 2.0")
+            .licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
+            .build();
+    }
+}

services/private_ip_manager/src/test/java/com/futurewei/alcor/privateipmanager/swagger/SwaggerJsonTest.java

@@ -0,0 +1,79 @@
+/*
+Copyright 2019 The Alcor Authors.
+
+Licensed 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 com.futurewei.alcor.privateipmanager.swagger;
+
+import org.springframework.boot.test.context.SpringBootTest;
+import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
+
+import org.springframework.mock.web.MockHttpServletResponse;
+import org.springframework.beans.factory.annotation.Autowired;
+
+import org.springframework.test.web.servlet.MockMvc;
+import org.springframework.test.web.servlet.MvcResult;
+
+import org.springframework.http.MediaType;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.springframework.test.context.junit4.SpringRunner;
+import java.io.BufferedWriter;
+import java.nio.charset.StandardCharsets;
+import java.nio.file.Files;
+import java.nio.file.Paths;
+
+import io.github.swagger2markup.Swagger2MarkupConverter;
+import io.github.swagger2markup.Swagger2MarkupProperties;
+import io.github.swagger2markup.Swagger2MarkupConfig;
+import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder;
+
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+import static org.springframework.test.web.servlet.result.MockMvcResultHandlers.print;
+
+@RunWith(SpringRunner.class)
+@SpringBootTest
+@AutoConfigureMockMvc
+public class SwaggerJsonTest{
+
+    @Autowired
+    private MockMvc mockMvc;
+
+    @Test
+    public void createSpringfoxSwaggerJson() throws Exception{
+        String outputDir = System.getProperty("io.springfox.staticdocs.outputDir");
+        MvcResult mvcResult = this.mockMvc.perform(get("/v2/api-docs")
+            .accept(MediaType.APPLICATION_JSON))
+            .andExpect(status().isOk())
+            .andReturn();
+
+        MockHttpServletResponse response = mvcResult.getResponse();
+        String swaggerJson = response.getContentAsString();
+        Files.createDirectories(Paths.get(outputDir));
+        try(BufferedWriter writer = Files.newBufferedWriter(Paths.get(outputDir, "swagger.json"), StandardCharsets.UTF_8)){
+            writer.write(swaggerJson);
+        }
+
+        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
+            .withGeneratedExamples()
+            .withInterDocumentCrossReferences()
+            .build();
+        Swagger2MarkupConverter.from(Paths.get(outputDir,"swagger.json"))
+            .withConfig(config)
+            .build()
+            .toFile(Paths.get(outputDir, "swagger"));
+    }
+
+}