springboot集成swagger2构建RESTful API文档

先介绍一下开发环境:

1. jdk版本是1.8
2. springboot的版本是1.4.1
3. 开发工具为 intellij idea

我们先引入swagger2的jar包,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>

//注解开启 swagger2 功能

@EnableSwagger2

//注解标示,这是一个配置类,@Configuation注解包含了@Component注解

//可以不用在使用@Component注解标记这是个bean了,

@Configuration

public class Swagger2 {

	/**

	 * 通过 createRestApi函数来构建一个DocketBean

	 * 函数名,可以随意命名,喜欢什么命名就什么命名

	 */

	@Bean

	public Docket createRestApi() {

		return new Docket(DocumentationType.SWAGGER_2)

				.apiInfo(apiInfo())//调用apiInfo方法,创建一个ApiInfo实例,里面是展示在文档页面信息内容

				.select()

				//控制暴露出去的路径下的实例

				//如果某个接口不想暴露,可以使用以下注解

				//@ApiIgnore 这样,该接口就不会暴露在 swagger2 的页面下

				.apis(RequestHandlerSelectors.basePackage("com.example"))

				.paths(PathSelectors.any())

				.build();

	}

    //构建 api文档的详细信息函数

	private ApiInfo apiInfo() {

		return new ApiInfoBuilder()

				//页面标题

				.title("Spring Boot 测试使用 Swagger2 构建RESTful API")

				//创建人

				.contact("贺小五")

				//版本号

				.version("1.0")

				//描述

				.description("API 描述")

				.build();

	}

}

@SpringBootApplication(scanBasePackages = {"com"})

//该注解包含了@Controller和@ResponseBody两个注解

@RestController

public class DemoApplication{

	public static void main(String[] args) {

		SpringApplication.run(DemoApplication.class, args);

	}

    /**

    * 以下函数的注释,不增加注解了,将在下面统一做描述

    */

	@ApiOperation(value = "测试post请求",notes="注意事项")

	@ApiImplicitParam(dataType = "User",name = "user",value = "用户信息",required = true)

	@RequestMapping(value = "/testPost",method = RequestMethod.POST)

	public String testPost(@RequestBody User user){

		return "success";

	}

	@ApiOperation(value = "测试get请求",notes="注意事项")

	@ApiImplicitParam(name = "id",value = "用户id",dataType = "String",paramType = "path")

	@RequestMapping(value = "/testGet/{id}",method = RequestMethod.GET)

	public String testGet(@PathVariable String id){

		return id;

	}

	@ApiOperation(value = "测试组合注解",notes="注意事项")

	@ApiImplicitParams({

			@ApiImplicitParam(dataType = "User",name = "user",value = "用户信息",required = true,paramType = "body"),

			@ApiImplicitParam(dataType = "string",name = "id",value = "用户id",required = true,paramType = "path")

	})

	@RequestMapping(value = "/joinAnnotation/{id}",method = RequestMethod.POST)

	public User joinAnnotation(@PathVariable String id,@RequestBody User user){

		return user;

	}

	@ApiIgnore

	public String testIgnore(){

		return "success";

	}

}

上面的页面,就是swagger2里面的页面,可以发现, apiInfo里面设置的内容在左边展示出来了,demo-application其实就是controller的类名,右边有三个按钮,分别是 Show/Hide,List Opertions和Expand Operations,三个按钮都可以打开,类下的接口,点击后,会得到如下一个效果页面:

可以发现,展示出来了,controller下的三个接口(其实有四个,只不过有一个我们用注解忽略了,在这不展示而已..)

这个,,截图比较烂,各位将就着看吧..别嫌弃...,我们点击try it out 按钮,就会发送请求,结果如下:

以上就是比较简单的demo测试文档啦,如果各位想配置更详细,就去官网看吧..地址我贴出来:

swagger官网地址:http://swagger.io/

本人常用注解说明：

@ApiOperation：用在方法上，说明方法的作用

1.     value: 表示接口名称
2.     notes: 表示接口详细描述 

@ApiImplicitParams：用在方法上包含一组参数说明

@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面

1. paramType：参数位置

• header 对应注解：@RequestHeader
• query 对应注解：@RequestParam
• path  对应注解: @PathVariable
• body 对应注解: @RequestBody

1. name：参数名
2. dataType：参数类型
3. required：参数是否必须传
4. value：参数的描述
5. defaultValue：参数的默认值

@ApiResponses：用于表示一组响应

@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息

1. code：状态码
2. message：返回自定义信息
3. response：抛出异常的类

@ApiIgnore: 表示该接口函数不对swagger2开放展示

以上这些就是我测试过的注解,并没有深究,有兴趣的,可以看看其它注解,或者源码,会比我描述的全很多,