代码项目地址:springboot_html
集成swagger
1.pom.xml集成swagger,然后reimport maven依赖
<!-- 构建Restful API -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
2.使用注解来进行启动swagger加载项目
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* @author jiaohongtao
* @version 1.0
* @since 2020年04月15日
*/
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
//为controller包路径
.apis(RequestHandlerSelectors.basePackage("com.example.springboot_html.controller"))
.paths(PathSelectors.any())
.build();
}
/**
* 构建 api文档的详细信息函数,注意这里的注解引用的是哪个
*/
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//页面标题
.title("Spring Boot 使用 Swagger2 构建RESTful API")
//创建人
.contact(new Contact("Jiao", "http://blog.jiaohongtao.com/", "jiaohongtaovip@163.com"))
//版本号
.version("1.0")
//描述
.description("此API由jiaohongtao提供")
.build();
}
}
3.配置Controller注解供API使用
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
/**
* @author jiaohongtao
* @since 2019/8/22 16:43
* @describtion 测试页面
*/
@RestController
@Api
public class TestController {
@RequestMapping("test")
@ApiOperation(value = "test", httpMethod = "GET")
public String test() {
return "test";
}
@RequestMapping("hello1")
@ApiOperation(value = "hello1", httpMethod = "GET")
public String hello1() {
return "hello1";
}
@RequestMapping("hello2")
@ApiOperation(value = "hello2", httpMethod = "GET")
public String hello2() {
return "hello2";
}
}
PS:更多参数请查看另一篇文章 swagger注解知识点
至此配置已经成功,现在可以通过url来访问
3.访问并测试使用
- 访问: http://ip:port/项目名/swagger-ui.html
- 测试结果
生成离线文档
1.pom.xml集成swagger离线文档依赖,然后reimport maven
<!-- 生成swagger离线文档 -->
<dependency>
<groupId>org.apache.maven</groupId>
<artifactId>maven-plugin-api</artifactId>
<version>3.6.0</version>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>org.apache.maven.plugin-tools</groupId>
<artifactId>maven-plugin-annotations</artifactId>
<version>3.5.2</version>
<scope>compile</scope>
</dependency>
<!-- Plugin dependencies -->
<dependency>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup</artifactId>
<version>1.3.3</version>
<scope>compile</scope>
</dependency>
<!-- Testing dependencies -->
<dependency>
<groupId>org.testng</groupId>
<artifactId>testng</artifactId>
<version>7.2.0</version>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
<version>4.12</version>
</dependency>
<dependency>
<groupId>org.assertj</groupId>
<artifactId>assertj-core</artifactId>
<version>3.13.2</version>
<scope>compile</scope>
</dependency>
<dependency>
<groupId>org.mockito</groupId>
<artifactId>mockito-core</artifactId>
<version>3.1.0</version>
<scope>compile</scope>
</dependency>
....
<!-- 生成swagger离线文档 -->
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-plugin-plugin</artifactId>
<version>3.4</version>
<configuration>
<skipErrorNoDescriptorsFound>false</skipErrorNoDescriptorsFound>
</configuration>
<executions>
<execution>
<id>default-descriptor</id>
<goals>
<goal>descriptor</goal>
</goals>
<phase>process-classes</phase>
</execution>
<execution>
<id>help-descriptor</id>
<goals>
<goal>helpmojo</goal>
</goals>
<phase>process-classes</phase>
</execution>
</executions>
</plugin>
2.添加生成离线文档类
/*
使用方法:
1.访问swagger在线文档,复制swagger.json
2.将swagger.json文件放到/src/test/resources/docs/swagger下,手动创建
3.执行需要的格式并可执行方法,已测:
shouldConvertIntoFile,shouldConvertIntoDirectory,
shouldConvertIntoMarkdown,shouldConvertFromUrl
*/
import io.github.swagger2markup.Swagger2MarkupProperties;
import io.github.swagger2markup.markup.builder.MarkupLanguage;
import org.apache.commons.io.FileUtils;
import org.apache.commons.io.IOUtils;
import org.apache.maven.plugin.MojoFailureException;
import org.junit.Before;
import org.junit.Test;
import org.mockito.Mockito;
import org.mockito.stubbing.Answer;
import java.io.File;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.util.Arrays;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;
import static org.assertj.core.api.Assertions.assertThat;
/**
* 生成文档测试类
* from: https://github.com/Swagger2Markup/swagger2markup-maven-plugin
*
* @author jiaohongtao
* @date 2020/4/15
*/
public class Swagger2MarkupMojoTest {
private static final String RESOURCES_DIR = "src/test/resources";
private static final String SWAGGER_DIR = "/docs/swagger";
private static final String INPUT_DIR = RESOURCES_DIR + SWAGGER_DIR;
private static final String SWAGGER_OUTPUT_FILE = "swagger";
private static final String SWAGGER_INPUT_FILE = "swagger.json";
private static final String OUTPUT_DIR = "target/generated-docs";
private File outputDir;
@Before
public void clearGeneratedData() throws Exception {
outputDir = new File(OUTPUT_DIR);
FileUtils.deleteQuietly(outputDir);
}
@Test
public void shouldSkipExecution() throws Exception {
//given
Swagger2MarkupMojo mojo = new Swagger2MarkupMojo();
mojo.outputFile = new File(OUTPUT_DIR, SWAGGER_OUTPUT_FILE).getAbsoluteFile();
mojo.skip = true;
//when
mojo.execute();
//then
assertThat(mojo.outputFile).doesNotExist();
}
@Test
public void shouldConvertIntoFile() throws Exception {
//given
Swagger2MarkupMojo mojo = new Swagger2MarkupMojo();
mojo.swaggerInput = new File(INPUT_DIR, SWAGGER_INPUT_FILE).getAbsoluteFile().getAbsolutePath();
mojo.outputFile = new File(OUTPUT_DIR, SWAGGER_OUTPUT_FILE).getAbsoluteFile();
//when
mojo.execute();
//then
Iterable<String> outputFiles = recursivelyListFileNames(outputDir);
assertThat(outputFiles).containsOnly("swagger.adoc");
}
@Test
public void shouldConvertIntoDirectory() throws Exception {
//given
Swagger2MarkupMojo mojo = new Swagger2MarkupMojo();
mojo.swaggerInput = new File(INPUT_DIR, SWAGGER_INPUT_FILE).getAbsoluteFile().getAbsolutePath();
mojo.outputDir = new File(OUTPUT_DIR).getAbsoluteFile();
//when
mojo.execute();
//then
Iterable<String> outputFiles = recursivelyListFileNames(mojo.outputDir);
assertThat(outputFiles).containsOnly("definitions.adoc", "overview.adoc", "paths.adoc", "security.adoc");
}
@Test
public void shouldConvertIntoDirectoryIfInputIsDirectory() throws Exception {
//given that the input folder contains a nested structure with Swagger files
Swagger2MarkupMojo mojo = new Swagger2MarkupMojo();
mojo.swaggerInput = new File(RESOURCES_DIR).getAbsoluteFile().getAbsolutePath();
mojo.outputDir = new File(OUTPUT_DIR).getAbsoluteFile();
//when
mojo.execute();
//then
Iterable<String> outputFiles = recursivelyListFileNames(new File(mojo.outputDir, SWAGGER_DIR));
assertThat(outputFiles).containsOnly("definitions.adoc", "overview.adoc", "paths.adoc", "security.adoc");
outputFiles = listFileNames(new File(mojo.outputDir, SWAGGER_DIR + "2"), false);
assertThat(outputFiles).containsOnly("definitions.adoc", "overview.adoc", "paths.adoc", "security.adoc");
}
@Test
public void shouldConvertIntoDirectoryIfInputIsDirectoryWithMixedSeparators() throws Exception {
//given that the input folder contains a nested structure with Swagger files but path to it contains mixed file
//separators on Windows (/ and \)
Swagger2MarkupMojo mojo = new Swagger2MarkupMojo();
String swaggerInputPath = new File(RESOURCES_DIR).getAbsoluteFile().getAbsolutePath();
mojo.swaggerInput = replaceLast(swaggerInputPath, "\\", "/");
mojo.outputDir = new File(OUTPUT_DIR).getAbsoluteFile();
//when
mojo.execute();
//then
Iterable<String> outputFiles = recursivelyListFileNames(new File(mojo.outputDir, SWAGGER_DIR));
assertThat(outputFiles).containsOnly("definitions.adoc", "overview.adoc", "paths.adoc", "security.adoc");
outputFiles = listFileNames(new File(mojo.outputDir, SWAGGER_DIR + "2"), false);
assertThat(outputFiles).containsOnly("definitions.adoc", "overview.adoc", "paths.adoc", "security.adoc");
}
@Test
public void shouldConvertIntoSubDirectoryIfMultipleSwaggerFilesInSameInput() throws Exception {
//given that the input folder contains two Swagger files
Swagger2MarkupMojo mojo = new Swagger2MarkupMojo();
mojo.swaggerInput = new File(INPUT_DIR).getAbsoluteFile().getAbsolutePath();
mojo.outputDir = new File(OUTPUT_DIR).getAbsoluteFile();
//when
mojo.execute();
//then
Iterable<String> outputFiles = recursivelyListFileNames(mojo.outputDir);
List<String> directoryNames = Arrays.asList(mojo.outputDir.listFiles()).stream().map(File::getName)
.collect(Collectors.toList());
assertThat(outputFiles).containsOnly("definitions.adoc", "overview.adoc", "paths.adoc", "security.adoc");
assertThat(outputFiles.spliterator().getExactSizeIfKnown()).isEqualTo(8); // same set of files twice
assertThat(directoryNames).containsOnly("swagger", "swagger2");
}
@Test
public void shouldConvertIntoSubDirectoryOneFileIfMultipleSwaggerFilesInSameInput() throws Exception {
//given that the input folder contains two Swagger files
Swagger2MarkupMojo mojo = new Swagger2MarkupMojo();
mojo.swaggerInput = new File(INPUT_DIR).getAbsoluteFile().getAbsolutePath();
mojo.outputDir = new File(OUTPUT_DIR).getAbsoluteFile();
mojo.outputFile = new File(SWAGGER_OUTPUT_FILE);
//when
mojo.execute();
//then
Iterable<String> outputFiles = recursivelyListFileNames(mojo.outputDir);
List<String> directoryNames = Arrays.asList(mojo.outputDir.listFiles()).stream().map(File::getName)
.collect(Collectors.toList());
assertThat(outputFiles).containsOnly("swagger.adoc");
assertThat(outputFiles.spliterator().getExactSizeIfKnown()).isEqualTo(2); // same set of files twice
assertThat(directoryNames).containsOnly("swagger", "swagger2");
}
@Test
public void shouldConvertIntoMarkdown() throws Exception {
//given
Map<String, String> config = new HashMap<>();
config.put(Swagger2MarkupProperties.MARKUP_LANGUAGE, MarkupLanguage.MARKDOWN.toString());
Swagger2MarkupMojo mojo = new Swagger2MarkupMojo();
mojo.swaggerInput = new File(INPUT_DIR, SWAGGER_INPUT_FILE).getAbsoluteFile().getAbsolutePath();
mojo.outputDir = new File(OUTPUT_DIR).getAbsoluteFile();
mojo.config = config;
//when
mojo.execute();
//then
Iterable<String> outputFiles = recursivelyListFileNames(mojo.outputDir);
assertThat(outputFiles).containsOnly("definitions.md", "overview.md", "paths.md", "security.md");
}
@Test
public void shouldConvertFromUrl() throws Exception {
//given
Swagger2MarkupMojo mojo = new Swagger2MarkupMojo();
// addr: ip:port/项目名/v2/api-docs,如果没有定义项目名,则为addr: ip:port/v2/api-docs
mojo.swaggerInput = "http://localhost:9090/spring_html/v2/api-docs";
mojo.outputDir = new File(OUTPUT_DIR).getAbsoluteFile();
//when
mojo.execute();
//then
Iterable<String> outputFiles = recursivelyListFileNames(mojo.outputDir);
assertThat(outputFiles).containsOnly("definitions.adoc", "overview.adoc", "paths.adoc", "security.adoc");
}
@Test(expected = MojoFailureException.class)
public void testMissingInputDirectory() throws Exception {
//given
Swagger2MarkupMojo mojo = new Swagger2MarkupMojo();
mojo.swaggerInput = new File(INPUT_DIR, "non-existent").getAbsoluteFile().getAbsolutePath();
//when
mojo.execute();
}
@Test(expected = MojoFailureException.class)
public void testUnreadableOutputDirectory() throws Exception {
//given
Swagger2MarkupMojo mojo = new Swagger2MarkupMojo();
mojo.swaggerInput = new File(INPUT_DIR, SWAGGER_INPUT_FILE).getAbsoluteFile().getAbsolutePath();
mojo.outputDir = Mockito.mock(File.class, (Answer) invocationOnMock -> {
if (!invocationOnMock.getMethod().getName().contains("toString")) {
throw new IOException("test exception");
}
return null;
});
//when
mojo.execute();
}
private static Iterable<String> recursivelyListFileNames(File dir) throws Exception {
return listFileNames(dir, true);
}
private static Iterable<String> listFileNames(File dir, boolean recursive) {
return FileUtils.listFiles(dir, null, recursive).stream().map(File::getName).collect(Collectors.toList());
}
private static void verifyFileContains(File file, String value) throws IOException {
assertThat(IOUtils.toString(file.toURI(), StandardCharsets.UTF_8)).contains(value);
}
private static String replaceLast(String input, String search, String replace) {
int lastIndex = input.lastIndexOf(search);
if (lastIndex > -1) {
return input.substring(0, lastIndex)
+ replace
+ input.substring(lastIndex + search.length(), input.length());
} else {
return input;
}
}
}
/*
* Copyright 2016 Robert Winkler
*
* 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.
*/
import io.github.swagger2markup.Swagger2MarkupConfig;
import io.github.swagger2markup.Swagger2MarkupConverter;
import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder;
import io.github.swagger2markup.utils.URIUtils;
import org.apache.commons.io.FileUtils;
import org.apache.commons.io.FilenameUtils;
import org.apache.commons.lang3.StringUtils;
import org.apache.maven.plugin.AbstractMojo;
import org.apache.maven.plugin.MojoExecutionException;
import org.apache.maven.plugin.MojoFailureException;
import org.apache.maven.plugins.annotations.Mojo;
import org.apache.maven.plugins.annotations.Parameter;
import java.io.File;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.Collection;
import java.util.HashMap;
import java.util.Map;
/**
* Basic mojo to invoke the {@link Swagger2MarkupConverter}
* during the maven build cycle
*/
@Mojo(name = "convertSwagger2markup")
public class Swagger2MarkupMojo extends AbstractMojo {
@Parameter(property = "swaggerInput", required = true)
protected String swaggerInput;
@Parameter(property = "outputDir")
protected File outputDir;
@Parameter(property = "outputFile")
protected File outputFile;
@Parameter
protected Map<String, String> config = new HashMap<>();
@Parameter(property = "skip")
protected boolean skip;
@Override
public void execute() throws MojoExecutionException, MojoFailureException {
if (skip) {
getLog().info("convertSwagger2markup is skipped.");
return;
}
if (getLog().isDebugEnabled()) {
getLog().debug("convertSwagger2markup goal started");
getLog().debug("swaggerInput: " + swaggerInput);
getLog().debug("outputDir: " + outputDir);
getLog().debug("outputFile: " + outputFile);
for (Map.Entry<String, String> entry : this.config.entrySet()) {
getLog().debug(entry.getKey() + ": " + entry.getValue());
}
}
try {
Swagger2MarkupConfig swagger2MarkupConfig = new Swagger2MarkupConfigBuilder(config).build();
if (isLocalFolder(swaggerInput)) {
getSwaggerFiles(new File(swaggerInput), true).forEach(f -> {
Swagger2MarkupConverter converter = Swagger2MarkupConverter.from(f.toURI())
.withConfig(swagger2MarkupConfig)
.build();
swaggerToMarkup(converter, true);
});
} else {
Swagger2MarkupConverter converter = Swagger2MarkupConverter.from(URIUtils.create(swaggerInput))
.withConfig(swagger2MarkupConfig).build();
swaggerToMarkup(converter, false);
}
} catch (Exception e) {
throw new MojoFailureException("Failed to execute goal 'convertSwagger2markup'", e);
}
getLog().debug("convertSwagger2markup goal finished");
}
private boolean isLocalFolder(String swaggerInput) {
return !swaggerInput.toLowerCase().startsWith("http") && new File(swaggerInput).isDirectory();
}
private void swaggerToMarkup(Swagger2MarkupConverter converter, boolean inputIsLocalFolder) {
if (outputFile != null) {
Path useFile = outputFile.toPath();
/*
* If user has specified input folder with multiple files to convert,
* and has specified a single output file, then route all conversions
* into one file under each 'new' sub-directory, which corresponds to
* each input file.
* Otherwise, specifying the output file with an input DIRECTORY means
* last file converted wins.
*/
if (inputIsLocalFolder) {
if (outputDir != null) {
File effectiveOutputDir = outputDir;
effectiveOutputDir = getEffectiveOutputDirWhenInputIsAFolder(converter);
converter.getContext().setOutputPath(effectiveOutputDir.toPath());
useFile = Paths.get(effectiveOutputDir.getPath(), useFile.getFileName().toString());
}
}
if (getLog().isInfoEnabled()) {
getLog().info("Converting input to one file: " + useFile);
}
converter.toFile(useFile);
} else if (outputDir != null) {
File effectiveOutputDir = outputDir;
if (inputIsLocalFolder) {
effectiveOutputDir = getEffectiveOutputDirWhenInputIsAFolder(converter);
}
if (getLog().isInfoEnabled()) {
getLog().info("Converting input to multiple files in folder: '" + effectiveOutputDir + "'");
}
converter.toFolder(effectiveOutputDir.toPath());
} else {
throw new IllegalArgumentException("Either outputFile or outputDir parameter must be used");
}
}
private File getEffectiveOutputDirWhenInputIsAFolder(Swagger2MarkupConverter converter) {
String outputDirAddendum = getInputDirStructurePath(converter);
if (multipleSwaggerFilesInSwaggerLocationFolder(converter)) {
/*
* If the folder the current Swagger file resides in contains at least one other Swagger file then the
* output dir must have an extra subdir per file to avoid markdown files getting overwritten.
*/
outputDirAddendum += File.separator + extractSwaggerFileNameWithoutExtension(converter);
}
return new File(outputDir, outputDirAddendum);
}
private String getInputDirStructurePath(Swagger2MarkupConverter converter) {
/*
* When the Swagger input is a local folder (e.g. /Users/foo/) you'll want to group the generated output in the
* configured output directory. The most obvious approach is to replicate the folder structure from the input
* folder to the output folder. Example:
* - swaggerInput is set to /Users/foo
* - there's a single Swagger file at /Users/foo/bar-service/v1/bar.yaml
* - outputDir is set to /tmp/asciidoc
* -> markdown files from bar.yaml are generated to /tmp/asciidoc/bar-service/v1
*/
String swaggerFilePath = new File(converter.getContext().getSwaggerLocation()).getAbsolutePath(); // /Users/foo/bar-service/v1/bar.yaml
String swaggerFileFolder = StringUtils.substringBeforeLast(swaggerFilePath, File.separator); // /Users/foo/bar-service/v1
return StringUtils.remove(swaggerFileFolder, getSwaggerInputAbsolutePath()); // /bar-service/v1
}
private boolean multipleSwaggerFilesInSwaggerLocationFolder(Swagger2MarkupConverter converter) {
Collection<File> swaggerFiles = getSwaggerFiles(new File(converter.getContext().getSwaggerLocation())
.getParentFile(), false);
return swaggerFiles != null && swaggerFiles.size() > 1;
}
private String extractSwaggerFileNameWithoutExtension(Swagger2MarkupConverter converter) {
return FilenameUtils.removeExtension(new File(converter.getContext().getSwaggerLocation()).getName());
}
private Collection<File> getSwaggerFiles(File directory, boolean recursive) {
return FileUtils.listFiles(directory, new String[]{"yaml", "yml", "json"}, recursive);
}
/**
* The 'swaggerInput' provided by the user can be anything; it's just a string. Hence, it could by Unix-style,
* Windows-style or even a mix thereof. This methods turns the input into a File and returns its absolute path. It
* will be platform dependent as far as file separators go but at least the separators will be consistent.
*/
private String getSwaggerInputAbsolutePath() {
return new File(swaggerInput).getAbsolutePath();
}
}
3.使用方法
- 使用方法:
-
1.访问swagger在线文档地址 http://ip:port/spring_html/v2/api-docs,创建swagger.json文件并将json复制到文件中
-
2.将swagger.json文件放到/src/test/resources/docs/swagger下,手动创建
-
3.执行需要的格式并可执行方法,已测:
shouldConvertIntoFile,shouldConvertIntoDirectory,
shouldConvertIntoMarkdown,shouldConvertFromUrl -
4.执行需要执行的方法,eg:shouldConvertIntoMarkdown,结果:
- 生成所有文档
- 文档内容
- 生成所有文档
-
终于总结好了,一个还在路上的猿。