Skip to content
This repository was archived by the owner on Mar 31, 2023. It is now read-only.

Commit 2ae412f

Browse files
skdongskdong
authored
Automatically generate Swagger documentation (#184)
1 parent d240ccc commit 2ae412f

15 files changed

Lines changed: 805 additions & 27 deletions

File tree

‎services/mac_manager/pom.xml‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,21 @@
1616

1717
<properties>
1818
<java.version>1.8</java.version>
19+
<swagger.output.dir>${project.build.directory}/swagger</swagger.output.dir>
20+
<swagger2markup.version>1.2.0</swagger2markup.version>
1921
</properties>
2022

23+
<repositories>
24+
<repository>
25+
<snapshots>
26+
<enabled>false</enabled>
27+
</snapshots>
28+
<id>jcenter-releases</id>
29+
<name>jcenter</name>
30+
<url>https://jcenter.bintray.com</url>
31+
</repository>
32+
</repositories>
33+
2134
<dependencies>
2235
<dependency>
2336
<groupId>org.springframework.boot</groupId>
@@ -71,6 +84,18 @@
7184
</exclusion>
7285
</exclusions>
7386
</dependency>
87+
<dependency>
88+
<groupId>io.springfox</groupId>
89+
<artifactId>springfox-swagger2</artifactId>
90+
<version>2.6.1</version>
91+
<scope>test</scope>
92+
</dependency>
93+
<dependency>
94+
<groupId>io.github.swagger2markup</groupId>
95+
<artifactId>swagger2markup-spring-restdocs-ext</artifactId>
96+
<version>${swagger2markup.version}</version>
97+
<scope>test</scope>
98+
</dependency>
7499
<dependency>
75100
<groupId>com.futurewei.alcor.common</groupId>
76101
<artifactId>AlcorCommonLib</artifactId>
@@ -85,6 +110,15 @@
85110
<groupId>org.springframework.boot</groupId>
86111
<artifactId>spring-boot-maven-plugin</artifactId>
87112
</plugin>
113+
<plugin>
114+
<groupId>org.apache.maven.plugins</groupId>
115+
<artifactId>maven-surefire-plugin</artifactId>
116+
<configuration>
117+
<systemPropertyVariables>
118+
<io.springfox.staticdocs.outputDir>${swagger.output.dir}</io.springfox.staticdocs.outputDir>
119+
</systemPropertyVariables>
120+
</configuration>
121+
</plugin>
88122
</plugins>
89123
</build>
90124

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

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
/*
2+
Copyright 2019 The Alcor Authors.
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
*/
16+
17+
package com.futurewei.alcor.macmanager.swagger;
18+
19+
import org.springframework.context.annotation.Bean;
20+
import org.springframework.context.annotation.Configuration;
21+
22+
import springfox.documentation.builders.PathSelectors;
23+
import springfox.documentation.builders.RequestHandlerSelectors;
24+
import springfox.documentation.service.ApiInfo;
25+
import springfox.documentation.spi.DocumentationType;
26+
import springfox.documentation.spring.web.plugins.Docket;
27+
import springfox.documentation.builders.ApiInfoBuilder;
28+
import springfox.documentation.swagger2.annotations.EnableSwagger2;
29+
30+
@Configuration
31+
@EnableSwagger2
32+
public class SwaggerConfig{
33+
@Bean
34+
public Docket api(){
35+
return new Docket(DocumentationType.SWAGGER_2)
36+
.apiInfo(apiInfo())
37+
.select()
38+
.apis(RequestHandlerSelectors.any())
39+
.paths(PathSelectors.regex("(?!/error).+"))
40+
.paths(PathSelectors.regex("(?!/actuator).+"))
41+
.build();
42+
}
43+
44+
private ApiInfo apiInfo(){
45+
return new ApiInfoBuilder()
46+
.title("Virtual MAC Manager")
47+
.description("Virtual MAC pool management")
48+
.license("Apache 2.0")
49+
.licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
50+
.build();
51+
}
52+
}

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

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
/*
2+
Copyright 2019 The Alcor Authors.
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
*/
16+
17+
package com.futurewei.alcor.macmanager.swagger;
18+
19+
import org.springframework.boot.test.context.SpringBootTest;
20+
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
21+
22+
import org.springframework.mock.web.MockHttpServletResponse;
23+
import org.springframework.beans.factory.annotation.Autowired;
24+
25+
import org.springframework.test.web.servlet.MockMvc;
26+
import org.springframework.test.web.servlet.MvcResult;
27+
28+
import org.springframework.http.MediaType;
29+
import org.junit.Test;
30+
import org.junit.runner.RunWith;
31+
import org.springframework.test.context.junit4.SpringRunner;
32+
import java.io.BufferedWriter;
33+
import java.nio.charset.StandardCharsets;
34+
import java.nio.file.Files;
35+
import java.nio.file.Paths;
36+
37+
import io.github.swagger2markup.Swagger2MarkupConverter;
38+
import io.github.swagger2markup.Swagger2MarkupProperties;
39+
import io.github.swagger2markup.Swagger2MarkupConfig;
40+
import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder;
41+
42+
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
43+
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
44+
import static org.springframework.test.web.servlet.result.MockMvcResultHandlers.print;
45+
46+
@RunWith(SpringRunner.class)
47+
@SpringBootTest
48+
@AutoConfigureMockMvc
49+
public class SwaggerJsonTest{
50+
51+
@Autowired
52+
private MockMvc mockMvc;
53+
54+
@Test
55+
public void createSpringfoxSwaggerJson() throws Exception{
56+
String outputDir = System.getProperty("io.springfox.staticdocs.outputDir");
57+
MvcResult mvcResult = this.mockMvc.perform(get("/v2/api-docs")
58+
.accept(MediaType.APPLICATION_JSON))
59+
.andExpect(status().isOk())
60+
.andReturn();
61+
62+
MockHttpServletResponse response = mvcResult.getResponse();
63+
String swaggerJson = response.getContentAsString();
64+
Files.createDirectories(Paths.get(outputDir));
65+
try(BufferedWriter writer = Files.newBufferedWriter(Paths.get(outputDir, "swagger.json"), StandardCharsets.UTF_8)){
66+
writer.write(swaggerJson);
67+
}
68+
69+
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
70+
.withGeneratedExamples()
71+
.withInterDocumentCrossReferences()
72+
.build();
73+
Swagger2MarkupConverter.from(Paths.get(outputDir,"swagger.json"))
74+
.withConfig(config)
75+
.build()
76+
.toFile(Paths.get(outputDir, "swagger"));
77+
}
78+
79+
}

‎services/private_ip_manager/pom.xml‎

Lines changed: 29 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -16,8 +16,21 @@
1616

1717
<properties>
1818
<java.version>1.8</java.version>
19+
<swagger.output.dir>${project.build.directory}/swagger</swagger.output.dir>
20+
<swagger2markup.version>1.2.0</swagger2markup.version>
1921
</properties>
2022

23+
<repositories>
24+
<repository>
25+
<snapshots>
26+
<enabled>false</enabled>
27+
</snapshots>
28+
<id>jcenter-releases</id>
29+
<name>jcenter</name>
30+
<url>https://jcenter.bintray.com</url>
31+
</repository>
32+
</repositories>
33+
2134
<dependencies>
2235
<dependency>
2336
<groupId>org.springframework.boot</groupId>
@@ -28,20 +41,25 @@
2841
<groupId>org.springframework.boot</groupId>
2942
<artifactId>spring-boot-starter-test</artifactId>
3043
<scope>test</scope>
31-
<exclusions>
32-
<exclusion>
33-
<groupId>org.junit.vintage</groupId>
34-
<artifactId>junit-vintage-engine</artifactId>
35-
</exclusion>
36-
</exclusions>
3744
</dependency>
3845

3946
<dependency>
4047
<groupId>org.projectlombok</groupId>
4148
<artifactId>lombok</artifactId>
4249
<version>1.18.0</version>
4350
</dependency>
44-
51+
<dependency>
52+
<groupId>io.springfox</groupId>
53+
<artifactId>springfox-swagger2</artifactId>
54+
<version>2.6.1</version>
55+
<scope>test</scope>
56+
</dependency>
57+
<dependency>
58+
<groupId>io.github.swagger2markup</groupId>
59+
<artifactId>swagger2markup-spring-restdocs-ext</artifactId>
60+
<version>${swagger2markup.version}</version>
61+
<scope>test</scope>
62+
</dependency>
4563
<dependency>
4664
<groupId>com.futurewei.alcor.common</groupId>
4765
<artifactId>AlcorCommonLib</artifactId>
@@ -66,7 +84,10 @@
6684
<groupId>org.apache.maven.plugins</groupId>
6785
<artifactId>maven-surefire-plugin</artifactId>
6886
<configuration>
69-
<skip>false</skip>
87+
<skip>true</skip>
88+
<systemPropertyVariables>
89+
<io.springfox.staticdocs.outputDir>${swagger.output.dir}</io.springfox.staticdocs.outputDir>
90+
</systemPropertyVariables>
7091
</configuration>
7192
</plugin>
7293
<plugin>

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

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
/*
2+
Copyright 2019 The Alcor Authors.
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
*/
16+
17+
package com.futurewei.alcor.privateipmanager.swagger;
18+
19+
import org.springframework.context.annotation.Bean;
20+
import org.springframework.context.annotation.Configuration;
21+
22+
import springfox.documentation.builders.PathSelectors;
23+
import springfox.documentation.builders.RequestHandlerSelectors;
24+
import springfox.documentation.service.ApiInfo;
25+
import springfox.documentation.spi.DocumentationType;
26+
import springfox.documentation.spring.web.plugins.Docket;
27+
import springfox.documentation.builders.ApiInfoBuilder;
28+
import springfox.documentation.swagger2.annotations.EnableSwagger2;
29+
30+
@Configuration
31+
@EnableSwagger2
32+
public class SwaggerConfig{
33+
@Bean
34+
public Docket api(){
35+
return new Docket(DocumentationType.SWAGGER_2)
36+
.apiInfo(apiInfo())
37+
.select()
38+
.apis(RequestHandlerSelectors.any())
39+
.paths(PathSelectors.regex("(?!/error).+"))
40+
.paths(PathSelectors.regex("(?!/actuator).+"))
41+
.build();
42+
}
43+
44+
private ApiInfo apiInfo(){
45+
return new ApiInfoBuilder()
46+
.title("Private IP Manager")
47+
.description("VPC Private IP lifecycle management(IPv4/6)")
48+
.license("Apache 2.0")
49+
.licenseUrl("http://www.apache.org/licenses/LICENSE-2.0.html")
50+
.build();
51+
}
52+
}

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

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
/*
2+
Copyright 2019 The Alcor Authors.
3+
4+
Licensed under the Apache License, Version 2.0 (the "License");
5+
you may not use this file except in compliance with the License.
6+
You may obtain a copy of the License at
7+
8+
http://www.apache.org/licenses/LICENSE-2.0
9+
10+
Unless required by applicable law or agreed to in writing, software
11+
distributed under the License is distributed on an "AS IS" BASIS,
12+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13+
See the License for the specific language governing permissions and
14+
limitations under the License.
15+
*/
16+
17+
package com.futurewei.alcor.privateipmanager.swagger;
18+
19+
import org.springframework.boot.test.context.SpringBootTest;
20+
import org.springframework.boot.test.autoconfigure.web.servlet.AutoConfigureMockMvc;
21+
22+
import org.springframework.mock.web.MockHttpServletResponse;
23+
import org.springframework.beans.factory.annotation.Autowired;
24+
25+
import org.springframework.test.web.servlet.MockMvc;
26+
import org.springframework.test.web.servlet.MvcResult;
27+
28+
import org.springframework.http.MediaType;
29+
import org.junit.Test;
30+
import org.junit.runner.RunWith;
31+
import org.springframework.test.context.junit4.SpringRunner;
32+
import java.io.BufferedWriter;
33+
import java.nio.charset.StandardCharsets;
34+
import java.nio.file.Files;
35+
import java.nio.file.Paths;
36+
37+
import io.github.swagger2markup.Swagger2MarkupConverter;
38+
import io.github.swagger2markup.Swagger2MarkupProperties;
39+
import io.github.swagger2markup.Swagger2MarkupConfig;
40+
import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder;
41+
42+
import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
43+
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
44+
import static org.springframework.test.web.servlet.result.MockMvcResultHandlers.print;
45+
46+
@RunWith(SpringRunner.class)
47+
@SpringBootTest
48+
@AutoConfigureMockMvc
49+
public class SwaggerJsonTest{
50+
51+
@Autowired
52+
private MockMvc mockMvc;
53+
54+
@Test
55+
public void createSpringfoxSwaggerJson() throws Exception{
56+
String outputDir = System.getProperty("io.springfox.staticdocs.outputDir");
57+
MvcResult mvcResult = this.mockMvc.perform(get("/v2/api-docs")
58+
.accept(MediaType.APPLICATION_JSON))
59+
.andExpect(status().isOk())
60+
.andReturn();
61+
62+
MockHttpServletResponse response = mvcResult.getResponse();
63+
String swaggerJson = response.getContentAsString();
64+
Files.createDirectories(Paths.get(outputDir));
65+
try(BufferedWriter writer = Files.newBufferedWriter(Paths.get(outputDir, "swagger.json"), StandardCharsets.UTF_8)){
66+
writer.write(swaggerJson);
67+
}
68+
69+
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
70+
.withGeneratedExamples()
71+
.withInterDocumentCrossReferences()
72+
.build();
73+
Swagger2MarkupConverter.from(Paths.get(outputDir,"swagger.json"))
74+
.withConfig(config)
75+
.build()
76+
.toFile(Paths.get(outputDir, "swagger"));
77+
}
78+
79+
}

0 commit comments

Comments
 (0)