SpringBoot学习之swagger2的集成和使用

Swagger是一个流行的API开发框架，用于生成、描述、调用和可视化REST风格的Web服务，这个框架以“开放API声明”为基础，对整个API的开发周期都提供了相应的解决方案，（包括设计、编码和测试，几乎支持所有语言。由于Spring的流行，出现了一个基于Spring的组件swagger-SpringMVC，用于将swagger集成到SpringMVC中来。

Swagger2介绍

  Swagger2是一个可以构建和调试RESTful接口文档的组件，利用Swagger2的注解可以快速的在项目中构建Api文档，并且提供了测试API的功能，Swagger让部署管理和使用功能强大的API从未如此简单。

SpringBoot集成

添加Swagger2依赖

<!-- 引入 Swagger2依赖 -->
<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>

创建Swagger2配置文件

主要是添加注解 @EnableSwagger2和定义Docket的bean类

@Configuration
@EnableSwagger2 // 开启 swagger2 功能
public class SwaggerConfig {

	private final String	name	= "独泪了无痕";
	private final String	url		= "https://github.com/dllwh/";
	private final String	email	= "[e-mail]";
	// 是否开启swagger，正式环境一般是需要关闭的，可根据springboot的多环境配置进行设置
	@Value(value = "${swagger.enabled}")
	private Boolean			swaggerEnabled;

	@Bean
	public Docket restApiDocket() {
		return new Docket(DocumentationType.SWAGGER_2) //
				.apiInfo(apiInfo()) // 用来创建该Api的基本信息（这些基本信息会展现在文档页面中）
				.enable(swaggerEnabled) // 是否开启
				.genericModelSubstitutes(DeferredResult.class) //
				.useDefaultResponseMessages(false) //
				.forCodeGeneration(false) //
				.pathMapping("/").select() // 选择那些路径和api会生成document
				.apis(RequestHandlerSelectors.basePackage("org.dllwh")) // 指定扫描的包路径
				.paths(PathSelectors.any())// 指定路径处理PathSelectors.any()代表所有的路径
				.build().pathMapping("/");// 创建
	}

	/**
	 * @方法描述:构建 api文档的详细信息函数
	 * @return
	 */
	private ApiInfo apiInfo() {
		// 联系人信息：联系人名字、联系人URL、联系人email
		Contact contact = new Contact(name, url, email);
		return new ApiInfoBuilder().title("SpringBoot-Swagger2集成和使用-demo示例") // 标题
				.description("Spring Boot 学习") // 描述
				.contact(contact)// 作者信息
				.version("0.0.1")// 版本
				// .extensions(null) //在basePath 基础上需要排除的url规则
				// .termsOfServiceUrl("") // 服务条款url
				// .license("") //许可证
				// .licenseUrl("") //许可证url
				.build();
	}
}

添加文档内容

修改Controller，添加API注解

@RestController
@Api(tags = "博客API")
public class SwaggerController {
	@Autowired
	private BlogService blogService;

	@GetMapping("getBlogById/{id}")
	@ApiOperation(value = "通过ID获取博客信息")
	@ApiImplicitParam(name = "id", value = "查询ID", required = true)
	public Map<String, Object> getBlogById(@PathVariable Integer id) {
		Blog blogById = blogService.getBlogById(id);
		if (blogById == null) {
			return Json.fail();
		} else {
			return Json.success(blogById);
		}
	}

	@DeleteMapping("deleteBlogById/{id}")
	@ApiOperation(value = "通过ID删除博客信息")
	public Map<String, Object> deleteBlogById(@PathVariable Integer id) {
		Blog blogById = blogService.getBlogById(id);
		if (blogById == null) {
			return Json.fail();
		} else {
			blogService.deleteBlogById(id);
			return Json.success(blogById);
		}
	}

	@GetMapping("getAllBlogs")
	@ApiOperation(value = "获取全部博客信息")
	public Map<String, Object> getAllBlogs() {
		List<Blog> allBlogs = blogService.getAllBlogs();
		if (allBlogs.size() == 0) {
			return Json.fail();
		} else {
			return Json.success(allBlogs);
		}
	}

	@PutMapping("insertBlog")
	@ApiOperation(value = "创建博客信息")
	public Map<String, Object> insertBlog(Blog blog) {
		blogService.insertBlog(blog);
		return Json.success(blog);
	}

	@PutMapping("updateBlog")
	@ApiOperation(value = "博客信息修改")
	public Map<String, Object> updateBlog(Blog blog) {
		blogService.updateBlog(blog);
		return Json.success(blog);
	}
}

属性配置

Swagger访问与使用

api首页路径

http://127.0.0.1:8219/swagger-ui.html

调试：点击需要访问的api列表，点击try it out!按钮，即可弹出一下页面：

执行：

结果：

Swagger常用属性说明

API 说明

Api	用于controller类上，描述Controller的作用，表示标识这个类是swagger的资源
ApiOperation	用在controller的方法上，说明方法的作用
ApiImplicitParams	用在controller的方法上，包含一组参数说明
ApiImplicitParam	用在@ApiImplicitParams的方法里边，指定一个请求参数的各个方面
ApiResponses	用在controller的方法上，用于表示一组响应
ApiRespons	用在 @ApiResponses里边，一般用于表达一个错误的响应信息
ApiModel	用在返回对象类上
ApiModelProperty	用在出入参数对象的字段上，描述对象的一个字段

注意事项

继承WebMvcConfigurationSupport之后，静态文件映射会出现问题，需要重新指定静态资源，在WebConfigurer中添加如下代码：

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
    registry.addResourceHandler("swagger-ui.html")
            .addResourceLocations("classpath:/META-INF/resources/");
    registry.addResourceHandler("/webjars/**")
            .addResourceLocations("classpath:/META-INF/resources/webjars/");
    registry.addResourceHandler("/favicon.ico")
            .addResourceLocations("classpath:/META-INF/resources/favicon.ico");
}

图形界面化

swagger-bootstrap-ui

swagger-bootstrap-ui是springfox-swagger的增强UI实现，为Java开发者在使用Swagger的时候，能拥有一份简洁、强大的接口文档体验。

<!-- Swagger-Bootstrap-UI -->
<dependency>
	<groupId>com.github.xiaoymin</groupId>
	<artifactId>swagger-bootstrap-ui</artifactId>
	<version>${last-version}</version>
</dependency>

swagger-bootstrap-ui 的默认访问地址是http://${host}:${port}/doc.html

相关使用方法，请查看Swagger-Bootstrap-UI用户指南

swagger-ui-layer

<dependency>
  <groupId>com.github.caspar-chen</groupId>
  <artifactId>swagger-ui-layer</artifactId>
  <version>${last-version}</version>
</dependency>

• swagger-ui-layer 最新版jar包地址：https://search.maven.org/search?q=g:com.github.caspar-chen%20AND%20a:swagger-ui-layer
• swagger-ui-layer 的默认访问地址是http://${host}:${port}/docs.html

总结

  本章节主要是对Swagger的集成和简单使用进行了说明，详细的用法，可自行搜索相关资料下，这里就不阐述了。

转载于:https://my.oschina.net/u/1030471/blog/3026866