1.关键操作
- 添加依赖
<!-- swagger2 依赖开始-->
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger2 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
<exclusions>
<exclusion>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
</exclusion>
<exclusion>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
</exclusion>
</exclusions>
</dependency>
<!-- 解决进入swagger页面报类型转换错误,排除2.9.2中的引用,手动增加1.5.21以上版本,这里选1.6.0版本-->
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
<version>1.6.0</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.swagger/swagger-models -->
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
<version>1.6.0</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.swagger/swagger-core -->
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-core</artifactId>
<version>1.6.0</version>
</dependency>
<!-- https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
<!--swagger2markup用的到-->
<!-- https://mvnrepository.com/artifact/org.pegdown/pegdown -->
<dependency>
<groupId>org.pegdown</groupId>
<artifactId>pegdown</artifactId>
<version>1.6.0</version>
<scope>test</scope>
</dependency>
<!-- https://mvnrepository.com/artifact/io.github.swagger2markup/swagger2markup
可能有两个包无法自动导入,需要手工处理,见本文第7小节
-->
<dependency>
<groupId>io.github.swagger2markup</groupId>
<artifactId>swagger2markup</artifactId>
<version>1.3.3</version>
</dependency>
<!-- swagger2 依赖结束-->
- application.yml加入swagger开关
swagger:
enable: true
- 编写配置类
config/Swagger2Config.java
package com.example.swagger2.config;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
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 alexhu
*/
@EnableSwagger2
@Configuration
@ConditionalOnProperty(name = "swagger.enable", havingValue = "true")
public class Swagger2Config {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.any())
.paths(PathSelectors.any())
.build();
}
//构建 api文档的详细信息函数
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
//页面标题
.title("功能测试")
//创建人
.contact(new Contact("Alex Hu", "www.example.com", "email@example.com"))
//版本号
.version("1.0")
//描述
.description("API 描述")
.build();
}
}
- 控制器类加注解,关键@Api/@ApiOperation/@ApiParam三个
controller/ExampleController.java
package com.example.swagger2.controller;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;
/**
* @author alexhu
*/
@Api(tags = "样例Controller",value = "控制器Demo")
@RestController
public class ExampleController {
@ApiOperation(value = "回显name",httpMethod = "GET")
@GetMapping("/echo/{name}")
public String echoName(@ApiParam(name = "name", value = "名字", required = true) @PathVariable("name") String name) {
return "Echo " + name;
}
@ApiOperation(value = "问候name",httpMethod = "GET")
@GetMapping("/hello")
public String helloName(@ApiParam(name = "name", value = "名字", required = true) @RequestParam("name") String name) {
return "Hello " + name;
}
}
- 编写测试代码,生成full-api-doc.md
package com.example.swagger2;
import io.github.swagger2markup.GroupBy;
import io.github.swagger2markup.Language;
import io.github.swagger2markup.Swagger2MarkupConfig;
import io.github.swagger2markup.Swagger2MarkupConverter;
import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder;
import io.github.swagger2markup.markup.builder.MarkupLanguage;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.junit4.SpringRunner;
import java.net.URL;
import java.nio.file.Paths;
@RunWith(SpringRunner.class)
@SpringBootTest
public class SwaggerTo {
/**
* 生成Markdown格式文档,并汇总成一个文件
* @throws Exception
*/
@Test
public void generateMarkdownDocsToFile() throws Exception {
// 输出Markdown到单文件
Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
.withMarkupLanguage(MarkupLanguage.MARKDOWN)
.withOutputLanguage(Language.ZH)
.withPathsGroupedBy(GroupBy.TAGS)
.withGeneratedExamples()
.withoutInlineSchema()
.build();
Swagger2MarkupConverter.from(new URL("http://localhost:8080/v2/api-docs"))
.withConfig(config)
.build()
.toFile(Paths.get("./docs/full-api-doc"));
}
}
- 启动项目,访问
http://localhost:8080/swagger-ui.html
2.常见问题–两个包无法导入
在这里 如果通过maven不能download这两个jar的同学可以去下载这两个jar
https://mvnrepository.com/artifact/nl.jworks.markdown_to_asciidoc/markdown_to_asciidoc/1.0
https://mvnrepository.com/artifact/ch.netzwerg/paleo-core/0.11.0
下载jar后本地安装到本地仓库:
mvn install:install-file -Dfile=~/Downloads/markdown_to_asciidoc-1.1.jar -DgroupId=nl.jworks.markdown_to_asciidoc -DartifactId=markdown_to_asciidoc -Dversion=1.0 -Dpackaging=jar
mvn install:install-file -Dfile=~/Downloads/paleo-core-0.14.0.jar -DgroupId=ch.netzwerg -DartifactId=paleo-core -Dversion=0.11.0 -Dpackaging=jar
脚本中是升级了,用新版本当旧版本用
3.参考链接
- https://blog.csdn.net/qq_40592377/article/details/89520847
- https://blog.csdn.net/jiangshuanshuan/article/details/84325692
- https://www.freesion.com/article/8284174476/