spring boot 动态api接口 springboot动态生成接口

背景介绍

在以往的项目开发中，项目的接口文档一般以word的形式，互相传阅。但是具有以下缺点：

1.接口更新了，文档没更新

2.系统版本多，接口版本也很多，不好管理

3.测试接口时，通常会使用postman等，http调试工具，如果接口url写错，或者某个必传参数遗漏，就会导致接口测试失败，比较繁琐。

Swagger有什么用?

swagger是一个流行的API开发框架，这个框架以“开放API声明”（OpenAPI Specification，OAS）为基础， 

对整个API的开发周期都提供了相应的解决方案，是一个非常庞大的项目（包括设计、编码和测试，几乎支持所有语言）。

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。 

总体目标是使客户端和文件系统作为服务器以同样的速度来更新。 

文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。Swagger 让部署管理和使用功能强大的API从未如此简单。

swagger2在系统中的主要作用，就是以注解的方式，侵入接口，动态生成可视化接口文档（swagger-ui）。

整体效果如下：

接口详情：

我们可以在这个文档中，完成对接口的调用测试。

SpringBoot 与 Swagger2

由于java的强大的注解功能,我们使用SpringBoot来结合Swagger2,在使用起来非常简单. 

由于Spring的流行，Marty Pitt编写了一个基于Spring的组件swagger-springmvc，用于将swagger集成到springmvc中来。

pom文件添加依赖

<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>

创建api

@Controller
@RequestMapping("user")
public class UserController {
	@RequestMapping(value = "/hello", method = RequestMethod.GET)
	public String hello() {
		return "hello";
	}
}

创建Swagger2配置类

package com.example.demo.utils;

import org.springframework.beans.factory.annotation.Value;
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
public class SwaggerConfig {
	/**
	 * 可以通过变量设置swagger-ui是否显示，比如测试环境可以暴露api文档，生产环境我们就关闭
	 */
	@Value("${swagger.enable}")
	private boolean enableSwagger;

	/**
	 * 固定写法，设置需要扫描的接口类，一般是controller，或者特定的api类 
	 * enable(enableSwagger)控制接口文档的ui的开关
	 */
	@Bean
	public Docket createRestApi() {
		return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo()).enable(enableSwagger).select()
				.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")).paths(PathSelectors.any())
				.build();
	}
	/**
	 * 在构建接口文档ui时，可以动态的显示一些我们这里添加的提示信息
	 */
	private ApiInfo apiInfo() {
		return new ApiInfoBuilder().title("springboot利用swagger构建api文档").description("rest api 文档构建利器")
				.termsOfServiceUrl("测试url").contact("taizhu").version("1.0").build();
	}
}

@Configuration // 定义配置类，加入到spring配置中去

以上的三个方法，为固定写法。

给启动类添加注解

@EnableSwagger2 // 开启swagger2注解功能

@ComponentScan(basePackages = { "com.example.demo.controller", "com.example.demo.service",
		"com.example.demo.datasource" })
@EnableAutoConfiguration
@EnableSwagger2
public class Demo1Application {

	public static void main(String[] args) {
		SpringApplication.run(Demo1Application.class, args);
	}

}

这时候，我们启动项目，访问:http://localhost/swagger-ui.html，就可以看到初步的接口API文档啦

 

 

Swagger2 注解使用

我们在UserController中增加一个不用传递参数的接口

@RestController
@RequestMapping(value = "/user", produces = "application/json")
@Api(description = "用户管理")
public class UserController {

	@RequestMapping(value = "/hello", method = RequestMethod.GET)
	public String hello() {
		return "hello";
	}

	ArrayList<User> users = new ArrayList<>();

	@ApiOperation(value = "获取用户列表", notes = "获取所有用户信息")
	@RequestMapping(value = "/getAll", method = RequestMethod.GET)
	public List<User> getAll() {
		users.add(new User(1, "luoji", 23));
		users.add(new User(2, "yewenjie", 24));
		return users;
	}
}

可以在接口文档中看到该接口

可以看到返回结果的字段类型，并且可以测试接口，获取到返回的结果。

但是我们如果想选择性的忽略某个字段,而不是把User类中的所有字段暴露出去呢?别着急,我们可以使用另一个注解:

@ApiModelProperty(hidden = true)

此注解可以作用在字段或者方法上,只要 hidden 属性为 true ,该字段或者方法就不会被生成api文档.

目前我们的ui页面中，接口显示参数的类型，但是没有字段的说明，识别起来很困难，还是不要着急，我们也有办法解决:

@ApiModelProperty(value = "用户名") 

value属性指明了该字段的含义(描述 Description),再次刷新浏览器试试:

如下:
 

package com.example.demo.model;

import io.swagger.annotations.ApiModelProperty;

public class User {
	@ApiModelProperty(hidden = true)
	private int id;
	@ApiModelProperty(value = "用户名")
	private String name;
	@ApiModelProperty(value = "年龄")
	private int age;

	public User() {
		super();
	}

	public User(int id, String name, int age) {
		super();
		this.id = id;
		this.name = name;
		this.age = age;
	}

	public int getId() {
		return id;
	}

	public void setId(int id) {
		this.id = id;
	}

	public String getName() {
		return name;
	}

	public void setName(String name) {
		this.name = name;
	}

	public int getAge() {
		return age;
	}

	public void setAge(int age) {
		this.age = age;
	}

}

那我们再次查看swagger-ui页面，发现id字段，不在接口文档中暴露了。

这时我们创建一个新的insert接口，用来接收对象类型的参数。

我们可以看到因为之前给实体类添加的@ApiModelProperty(value = "用户名")注解和 @ApiModelProperty(hidden = true)注解生效了。

参数不单提示类型，还有备注，而且不需要对外暴露的参数，也不会暴露出来。

 

此时，我们在创建一个接口，通过url来接收参数：

@ApiOperation(value = "查询用户", notes = "查询用户信息")
	@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")
	@RequestMapping(value = "/query/{id}", method = RequestMethod.GET)
	public Integer query(@PathVariable(value = "id") Integer id) {
		return id;
	}

启动项目。打开swagger-ui页面，测试接口，查看是否返回了传入参数。

OK，接口接收到了页面传入参数，并且正确返回，测试通过。

最后，我们创建一个复杂的参数接口，即要接收url传参，又要接收一个对象类型传参

package com.example.demo.controller;

import java.util.ArrayList;
import java.util.List;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestMethod;
import org.springframework.web.bind.annotation.RestController;

import com.example.demo.model.User;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;

@RestController
@RequestMapping(value = "/user", produces = "application/json")
@Api(description = "用户管理")
public class UserController {

	@RequestMapping(value = "/hello", method = RequestMethod.GET)
	public String hello() {
		return "hello";
	}

	ArrayList<User> users = new ArrayList<>();

	@ApiOperation(value = "获取用户列表", notes = "获取所有用户信息")
	@RequestMapping(value = "/getAll", method = RequestMethod.GET)
	public List<User> getAll() {
		users.add(new User(1, "luoji", 23));
		users.add(new User(2, "yewenjie", 24));
		return users;
	}

	@ApiOperation(value = "新增用户", notes = "新增用户信息")
	@RequestMapping(value = "/insert", method = RequestMethod.GET)
	public User insert(User user) {
		users.add(user);
		return user;
	}

	@ApiOperation(value = "查询用户", notes = "查询用户信息")
	@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Integer", paramType = "path")
	@RequestMapping(value = "/query/{id}", method = RequestMethod.GET)
	public Integer query(@PathVariable(value = "id") Integer id) {
		return id;
	}

	/**
	 * 根据id修改用户信息
	 * 
	 * @param user
	 * @return
	 */
	@ApiOperation(value = "更新信息", notes = "根据url的id来指定更新用户信息")
	@ApiImplicitParams({
			@ApiImplicitParam(name = "id", value = "用户ID", required = true, dataType = "Long", paramType = "path"),
			@ApiImplicitParam(name = "user", value = "用户实体user", required = true, dataType = "User") })
	@RequestMapping(value = "user/{id}", method = RequestMethod.PUT)
	public User update(@PathVariable("id") Integer id, User user) {
		return user;
	}

}

启动项目，打开swagger-ui页面，对新接口进行调用

调用成功！

swagger2中的注解：

swagger通过注解表明该接口会生成文档，包括接口名、请求方法、参数、返回信息的等等，如： 

@ApiIgnore：使用注解忽略该API，不会参与文档生成

@ApiOperation：描述该api,如： @ApiOperation(value=”创建用户”, notes=”根据User对象创建用户”)

请求方法：@RequestMapping(value = “user”, method = RequestMethod.POST)

参数x信息：@ApiImplicitParam(name = “user”, value = “用户详细实体user”, required = true, dataType = “User”)

@Api：修饰整个类，描述Controller的作用

@ApiParam：单个参数描述

@ApiModel：用对象来接收参数

@ApiResponses：HTTP响应整体描述

@ApiProperty：用对象接收参数时，描述对象的一个字段

Swagger2 基本使用(重点加粗显示)：

@Api: 描述类/接口的主要用途

@ApiOperation: 描述方法用途

@ApiImplicitParam: 描述方法的参数

@ApiImplicitParams: 描述方法的参数(Multi-Params)

可以在上面 创建用户的方法上添加 @ApiImplicitParam(name = "user", value = "用户详细实体user", required = true, dataType = "User")试试看.

@ApiParam:请求属性

@ApiIgnore: 忽略某类/方法/参数的文档

注意与 @ApiModelProperty(hidden = true)不同, @ApiIgnore 不能用在模型数据上

@ApiResponse：响应配置

如: @ApiResponse(code = 400, message = "无效的用户信息") ,注意这只是在 生成的Swagger文档上有效,不要和实际的客户端调用搞混了. 
通常我们都是统一JSON返回,用不到这个注解

@ApiResponses：响应集配置

@ResponseHeader: 响应头设置

例如: @ResponseHeader(name=”head1”,description=”response head conf”)

@ApiModelProperty:添加和操作模型属性的数据

Swagger-ui页面的汉化

简单的说，就是spring boot 会优先读取resource下面的静态资源。所以将依赖的swagger-ui的jar包里面的swagger-ui.html，拷贝出来，并放在

src/main/resources/META-INF/resources 路径下，然后在页面中，引入我们另外在下载到本地的汉化版的js文件

这样子，每次在打开swagger-ui.html时，都会打开本地的页面，从而加载本地引入的汉化js，达到汉化效果。

汉化的具体请百度。下面是一个汉化后的效果。