Springboot集成Swagger

1、首先在POM文件添加依赖：

<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger2</artifactId>
	<version>2.8.0</version>
</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-swagger-ui</artifactId>
	<version>2.8.0</version>
	</dependency>
<dependency>
	<groupId>io.springfox</groupId>
	<artifactId>springfox-bean-validators</artifactId>
	<version>2.8.0</version>
</dependency>

2、创建Swagger的配置类SwaggerConfiguration

@Configuration
@EnableSwagger2
public class SwaggerConfiguration {


    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).enable(true)
                .select().apis(RequestHandlerSelectors.basePackage("com.baidu.example"))  //从com.baidu.example包下搜索接口
                .paths(PathSelectors.any()).build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder().title("XX接口说明文档")
                .description("该系统XX")
                .termsOfServiceUrl("http://www.baidu.com")
                .contact(new Contact("who", "http://www.baidu.com", "api@baidu.com"))
                .version(“1.0.0”).build();
    }
}

3、添加API注解

接口/实体	注解位置	示例
Controller	类上	@Api(tags = "角色管理")
Controller	方法上	@ApiOperation("保存新建的角色信息")
Controller	RequestParam参数上	@ApiParam(value = "角色名", required = true)
Entity	类上	@ApiModel("角色信息")
Entity	属性上	@ApiModelProperty(value = "角色名", required = true)

4、由于生成文档需要通过API获取swagger注解生成的json文件，所以这个生成文件的过程可以放在单元测试里

public class Swagger2MarkupTest extends ControllerBaseTest {

    @Test
    public void createSpringfoxSwaggerJson() throws Exception {
        String outputDir = "target/swagger";

        MvcResult mvcResult = assertGetRequestOKJsonReturn("/v2/api-docs");
        String swaggerJson = mvcResult.getResponse().getContentAsString();

        Files.createDirectories(Paths.get(outputDir));
        try (BufferedWriter writer = Files.newBufferedWriter(Paths.get(outputDir, "swagger.json"),
                StandardCharsets.UTF_8)) {
            writer.write(swaggerJson);
        }
    }
}

5、使用maven插件生成html和pdf接口文档

① 在POM文件里配置以下属性：

<properties>
	<asciidoctor.input.directory>${project.basedir}/src/main/docs</asciidoctor.input.directory>			
 <generated.asciidoc.directory>${project.build.directory}/asciidoc/generated</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>
	<swagger.input>${project.build.directory}/swagger/swagger.json</swagger.input>
</properties>

※${swagger.input}是前面单元测试里生成json文件的路径。

② 设置仅在maven的Profile=test时，执行生成html和pdf的编译工作：

<profile>
	<id>test</id>
		<build>
			<plugins>
				<!-- First, use the swagger2markup plugin to generate asciidoc -->
				<plugin>
					<groupId>io.github.swagger2markup</groupId>
					<artifactId>swagger2markup-maven-plugin</artifactId>
					<version>1.3.4</version>
					<dependencies>
						<dependency>
							<groupId>io.github.swagger2markup</groupId>
							<artifactId>swagger2markup-import-files-ext</artifactId>
							<version>1.3.1</version>
						</dependency>
					<dependency>
						<groupId>io.github.swagger2markup</groupId>
						<artifactId>swagger2markup-spring-restdocs-ext</artifactId>
						<version>1.3.1</version>
					</dependency>
				</dependencies>
				<configuration>
					<swaggerInput>${swagger.input}</swaggerInput>
					<outputDir>${generated.asciidoc.directory}</outputDir>
					<config>
					<swagger2markup.markupLanguage>ASCIIDOC</swagger2markup.markupLanguage>
					<swagger2markup.pathsGroupedBy>TAGS</swagger2markup.pathsGroupedBy>
					</config>
				</configuration>
				<executions>
					<execution>
						<phase>test</phase>
						<goals>
							<goal>convertSwagger2markup</goal>
						</goals>
					</execution>
				</executions>
			</plugin>

			<!-- Run the generated asciidoc through Asciidoctor to generate other 
						documentation types, such as PDFs or HTML5 -->
			<plugin>
				<groupId>org.asciidoctor</groupId>
				<artifactId>asciidoctor-maven-plugin</artifactId>
				<version>1.5.6</version>
				<dependencies>
					<dependency>
						<groupId>org.asciidoctor</groupId>
						<artifactId>asciidoctorj-pdf</artifactId>
						<version>1.5.0-alpha.16</version>
					</dependency>
					<dependency>
						<groupId>org.jruby</groupId>
						<artifactId>jruby-complete</artifactId>
						<version>1.7.26</version>
					</dependency>
				</dependencies>
				<configuration>
					<sourceDirectory>${asciidoctor.input.directory}</sourceDirectory>
			<sourceDocumentName>${project.name}.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>
				</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>
	</build>

	<activation>
		<property>
			<name>env</name>
			<value>test</value>
		</property>
	</activation>
</profile>

※org.asciidoctor的插件如果使用其他版本组合，可能导致pdf文件无法生成，可以组合尝试其他版本。

※<sourceDocumentName>${project.name}.adoc</sourceDocumentName>是把json转成的adoc文档统一合并成一个文件的配置文件，该文件需要放在${asciidoctor.input.directory}路径下，按以下内容保存，其中generated表示${generated.asciidoc.directory}路径：

include::{generated}/overview.adoc[]
include::{generated}/paths.adoc[]
include::{generated}/security.adoc[]
include::{generated}/definitions.adoc[]

※由于生成pdf的插件使用的是日文编码，所以会导致部分中文缺失，虽然也有解决办法，但都不是自动化的，需要手动去操作，比较麻烦。实际上，html文档已经满足开发要求，pdf文档中文缺失的问题并不会造成影响。

※这两个插件需要连接jcenter的仓库，我们可以统一在maven的setting.xml配置文件里配置，并将Profile配置成test，与编译的Profile保持一致。

<profile>
      <id>test</id>
      <pluginRepositories>
		<pluginRepository>
			<id>jcenter-snapshots</id>
			<name>jcenter</name>
			<url>http://oss.jfrog.org/artifactory/oss-snapshot-local/</url>
		</pluginRepository>
		<pluginRepository>
			<snapshots>
				<enabled>false</enabled>
			</snapshots>
			<id>jcenter-releases</id>
			<name>jcenter</name>
			<url>http://jcenter.bintray.com</url>
		</pluginRepository>
      </pluginRepositories>
</profile>

6、使用mvn test命令将从单元测试生成swagger.json到maven插件转换成html文档整个过程串联起来

mvn test -P test

执行成功后，可以看到如下输出：

7、API调试

假如调试本地启动的8080端口工程，只要集成了swagger-ui，就可以通过以下url访问，并进行API的调试：

http://localhost:8080/swagger-ui.html

 

转载于:https://my.oschina.net/u/1445585/blog/1840841