虽然说是很简单的功能,但是在此记录一下
首先导入maven映射:
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
因为springfox包含了swagger2,所以我们直接引用springfox包下的swagger2就好了。第一个映射是swagger2的核心,第二个映射是swagger2显示的ui界面。
然后我们在项目里添加swagger2的配置类:
@Configuration
@EnableSwagger2
public class SwaggerConfig extends WebMvcConfigurerAdapter {
@Bean
public Docket api() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.xxx.xxx")) //此处写入你的包名
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("测试接口文档") //生成接口文档的title
.description("测试接口文档说明") //接口文档的描述
.version("1.0") //版本号
.build();
}
}
@EnableSwagger2这个注解代表了启动swagger2。
当我们配置好这个类之后启动项目直接可以访问项目节点:127.0.0.1:8080/swagger-ui.html
可以直接看到接口文档的一些摘要,是不是很简单。当然我们不止这些。
接下来我们配置生成html和pdf.
我们继续在pom文件添加:(注意是在properties节点下)
<properties>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
<java.version>1.8</java.version>
<snippetsDirectory>${project.build.directory}/generated-snippets</snippetsDirectory>
<asciidoctor.input.directory>${project.basedir}/docs/asciidoc</asciidoctor.input.directory>
<generated.asciidoc.directory>${project.build.directory}/asciidoc</generated.asciidoc.directory>
<asciidoctor.html.output.directory>${project.build.directory}/asciidoc/html</asciidoctor.html.output.directory>
<asciidoctor.pdf.output.directory>${project.build.directory}/asciidoc/pdf</asciidoctor.pdf.output.directory>
</properties>
然后我们继续在plugins节点下添加打包插件:
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
</plugin>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-resources-plugin</artifactId>
<configuration>
<encoding>UTF-8</encoding>
<useDefaultDelimiters>true</useDefaultDelimiters>
</configuration>
</plugin>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>1.5.3</version>
<!--生成PDF-->
<dependencies>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj-pdf</artifactId>
<version>1.5.0-alpha.14</version>
</dependency>
<dependency>
<groupId>org.jruby</groupId>
<artifactId>jruby-complete</artifactId>
<version>1.7.21</version>
</dependency>
</dependencies>
<!--文档生成配置-->
<configuration>
<sourceDirectory>${asciidoctor.input.directory}</sourceDirectory>
<sourceDocumentName>index.adoc</sourceDocumentName>
<attributes>
<doctype>book</doctype>
<toc>left</toc>
<toclevels>3</toclevels>
<numbered></numbered>
<hardbreaks></hardbreaks>
<sectlinks></sectlinks>
<sectanchors></sectanchors>
<generated>${generated.asciidoc.directory}</generated>
</attributes>
<skip>false</skip> <!-- 值为true 是在打包的时候跳过测试用例的执行,默认为false-->
</configuration>
<!--因为每次执行只能处理一个后端,所以对于每个想要的输出类型,都是独立分开执行-->
<executions>
<execution>
<id>output-html</id>
<phase>test</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>html5</backend>
<outputDirectory>${asciidoctor.html.output.directory}</outputDirectory>
</configuration>
</execution>
<execution>
<id>output-pdf</id>
<phase>test</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>pdf</backend>
<outputDirectory>${asciidoctor.pdf.output.directory}</outputDirectory>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
然后细心的已经看到生成html需要一个文件来支持,对 就是index.doc文件。
我们需要在项目的根目录创建docs/asciidoc/index.adoc 这个index.adoc文件的内容是:
include::{generated}/overview.adoc[]
include::{generated}/definitions.adoc[]
include::{generated}/paths.adoc[]
主要是把swagger2生成的文件内容渲染到我们需要的html或pdf。
接下来就是接口:
在接口也就是controller添加:
@RestController
@Api(value="测试控制器",tags={"测试操作接口"})
@RequestMapping(value = "/")
public class TestController {
@ResponseBody
@ApiOperation(value="测试", notes="测试方法")
@RequestMapping(value = "/test",method = { RequestMethod.POST})
public void test(@RequestBody TestBean testBean) {
}
}
然后就是实体:
@ApiModel(value = "TestBean")
public class TestBean implements Serializable {
private static final long serialVersionUID = 1L;
@ApiModelProperty(value="传入id",required = true)
private String id;
}
注解解释:
@Api 主要是在接口处,标示这个接口是做什么的
@ApiOperation主要在接口方法体,标示这个接口操作
@ApiModel 主要是在参数实体,标示这个实体是做什么的
@ApiModelProperty 参数实体的属性,标示属性作用(如果是必选项可以添加 required = true,默认是false)
添加测试用例:
@AutoConfigureMockMvc
@AutoConfigureRestDocs(outputDir = "target/generated-snippets")
@RunWith(SpringRunner.class)
@SpringBootTest
public class ApplicationTests {
private String snippetDir = "target/generated-snippets";
private String outputDir = "target/asciidoc";
@Autowired
private MockMvc mockMvc;
@After
public void Test() throws Exception {
// 得到swagger.json,写入outputDir目录中
mockMvc.perform(get("/v2/api-docs").accept(MediaType.APPLICATION_JSON))
.andDo(SwaggerResultHandler.outputDirectory(outputDir).build())
.andExpect(status().isOk())
.andReturn();
// 读取上一步生成的swagger.json转成asciiDoc,写入到outputDir
// 这个outputDir必须和插件里面<generated></generated>标签配置一致
Swagger2MarkupConverter.from(outputDir + "/swagger.json")
.withPathsGroupedBy(GroupBy.TAGS)// 按tag排序
.withMarkupLanguage(MarkupLanguage.ASCIIDOC)// 格式
.withExamples(snippetDir)
.build()
.intoFolder(outputDir);// 输出
}
@Test
public void TestApi() throws Exception {}
}
因为插件是根据测试用例来生成html的, 所以需要执行测试用例来完成最后一步。至此,全部完成swagger2的配置了。