Swagger

swagger的安装与使用

1.swagger介绍

Swagger是全球最大的符合OpenAPI规范（OAS）的API开发工具框架，它支持从设计、文档到测试、部署的整个API生命周期的开发。

简而言之，swagger可以帮助程序员自动生成API（在线或离线）文档，支持接口测试等。

swagger生成API、导出文档过程示意图：

2.swagger的使用

这里我们介绍spring boot继承swagger框架

首先在pom.xml文件中添加swagger依赖

        <!--swagger-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>
        <dependency>  
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>

添加swagger的配置类

在Spring Boot的启动类同级包下，建立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.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@Configuration
@EnableSwagger2
public class Swagger2 {
	@Bean
	public Docket createRestApi() {
		return new Docket(DocumentationType.SWAGGER_2)
				.apiInfo(apiInfo())
				.select()     
                 .apis(RequestHandlerSelectors.basePackage("com.example.demo")) // 设置扫描的包
				.paths(PathSelectors.any())
				.build();
	}
	
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder()
				.title("springboot利用swagger构建api文档") // 文档的标题
				.description("简单优雅的restfun风格") // Overview
				.termsOfServiceUrl("http://blog.csdn.net") // license 信息 
				.version("1.0") // 版本
				.build();
	}
}

这个配置类产生的效果如图：

Controller类

package com.example.demo;

import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.ResponseBody;

import org.springframework.http.MediaType;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;

import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;

/**
 * HEllO
 *
 * @author liufenglin
 * @date 2017年12月2日
 */
@Controller
@Api
public class HelloController {
	
	@ApiOperation(value="获取用户详细信息", notes="根据url的id来获取用户详细信息")
	@ApiImplicitParams(value = 
	{ @ApiImplicitParam(name = "body", value = "请求体", dataType = "String", paramType = "path"),
	@ApiImplicitParam(name = "para", value = "参数", required = true, dataType = "String", paramType = "path")
	}
	)
	@ApiResponses(value = { @ApiResponse(code = 0, message = "No Name Provided")})
	@ResponseBody
	@RequestMapping(value = "/pay", method = RequestMethod.POST)
	public  String say(@RequestBody (required=false) String body) {
		if (body != null)
		System.out.println(body);
		else 
			System.out.println("12341251234");
		return "Hello Spring Boot!";
	}
	
}

访问在线api的URI：http://localhost:9090/swagger-ui.html效果如图：

paramType参数的含义：

header–>请求参数的获取：@RequestHeader query–>直接跟参数完成自动映射赋值，用@RequestParam获取请求参数 path–>以url地址的形式提交数据，用@PathVariable获取请求参数 body->以流的形式提交仅支持POST form->参数在request headers里边提交 value：参数的意思

3.swagger导出html

增加pom配置

<dependencies>
  
<dependency>
    <groupId>io.github.swagger2markup</groupId>
    <artifactId>swagger2markup</artifactId>
    <version>1.3.2</version>
</dependency>

</dependencies>


<repositories>
    <repository>
        <snapshots>
            <enabled>false</enabled>
        </snapshots>
        <id>jcenter-releases</id>
        <name>jcenter</name>
        <url>http://jcenter.bintray.com</url>
    </repository>
</repositories>

通过运行测试类将http://localhost:9090/v2/api-docs的json转化为adoc格式文档并存储（使用swagger2markup-maven-plugin插件容易报错，还是用测试类转换更稳定）

package com.example.demo;

import java.net.MalformedURLException;
import java.net.URL;
import java.nio.file.Paths;

import org.junit.Test;

import io.github.swagger2markup.Swagger2MarkupConfig;
import io.github.swagger2markup.Swagger2MarkupConverter;
import io.github.swagger2markup.builder.Swagger2MarkupConfigBuilder;
import io.github.swagger2markup.markup.builder.MarkupLanguage;

public class SwaggerToHTMLandPDFTest {
    
    @Test
    public void test() throws MalformedURLException {
    	
        // 输出Ascii格式
        Swagger2MarkupConfig config = new Swagger2MarkupConfigBuilder()
                .withMarkupLanguage(MarkupLanguage.ASCIIDOC)
                .build();

        Swagger2MarkupConverter.from(new URL("http://localhost:9090/v2/api-docs"))
                .withConfig(config)
                .build()
                .toFile(Paths.get("src/docs/asciidoc/generated/all"));
//                .toFolder(Paths.get("src/docs/asciidoc/generated"));
    	
    } 
}

执行测试代码后生成的adoc文件，如图：

注意：在swagger.json转adoc时，项目一定要运行，确保http://localhost:9090/v2/api-docs路径可以访问

在pom中添加插件生成html

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>1.5.6</version>
    <configuration>
        <sourceDirectory>src/docs/asciidoc/generated</sourceDirectory>
        <outputDirectory>src/docs/asciidoc/html</outputDirectory>
        <backend>html</backend>
        <sourceHighlighter>coderay</sourceHighlighter>
        <attributes>
            <toc>left</toc>
        </attributes>
    </configuration>
</plugin>

然后，执行maven命令asciidoctor:process-asciidoc

生成html文件如图：

效果如图：

参考文档

Swagger2Markup Documentation