springboot结合swagger2自动生成接口文档

1.在POM.xml中引入相关的Jar依赖

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

2. 开启Springboot 对swagger2的支持

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

@SpringBootApplication // 组件扫描
@EnableSwagger2 //开启swagger2的支持
public class SwaggerExampleApplication {

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

3.定义UserController Restful Api

package com.swagger.controller;

import com.swagger.bean.User;
import io.swagger.annotations.*;
import org.springframework.web.bind.annotation.*;
import springfox.documentation.annotations.ApiIgnore;

import javax.validation.Valid;
import java.util.ArrayList;
import java.util.List;

/**
 * Created by daizhao.
 * User: tony
 * Date: 2018-3-21
 * Time: 13:54
 * info:
 */
@RestController
@RequestMapping("/user")
@Api("UserController API")
public class UserController {

    @ApiOperation("建立用户")
    @PostMapping("/users")
    public User create(@RequestBody @Valid User user) {
        return user;
    }

    @ApiOperation("用户详情")
    @GetMapping("/users/{id}")
    public User findById(@PathVariable Long id) {
        return new User("bbb", 21, "上海", "aaa@bbb.com");
    }

    @ApiOperation("用户列表")
    @GetMapping("/users")
    public List<User> list(@ApiParam("查看第几页") @RequestParam int pageIndex,
                           @ApiParam("每页多少条") @RequestParam int pageSize) {
        List<User> result = new ArrayList<>();
        result.add(new User("aaa", 50, "北京", "aaa@ccc.com"));
        result.add(new User("bbb", 21, "广州", "aaa@ddd.com"));
        return result;
    }

    //@ApiIgnore
    @ApiOperation("删除列表")
    @DeleteMapping("/users/{id}")
    public String deleteById(@PathVariable Long id) {
        return "delete user : " + id;
    }

}

相关的User类

package com.swagger.bean;

/**
 * Created by daizhao.
 * User: tony
 * Date: 2018-3-21
 * Time: 10:56
 * info:
 */
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

import javax.validation.constraints.*;

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel("用户基本信息")
public class User {

    @ApiModelProperty("姓名")
    @Size(max = 20)
    private String name;
    @ApiModelProperty("年龄")
    @Max(150)
    @Min(1)
    private Integer age;
    @NotNull
    private String address;
    @Pattern(regexp = "^[a-zA-Z0-9_-]+@[a-zA-Z0-9_-]+(\\.[a-zA-Z0-9_-]+)+$")
    private String email;

}

4.说明：

    

@Api：用在类上，说明该类的做用
@ApiOperation：用在方法上，说明方法的做用
@ApiImplicitParams：用在方法上包含一组参数说明
@ApiImplicitParam：用在@ApiImplicitParams注解中，指定一个请求参数的各个方面
paramType：参数放在哪一个地方
header-->请求参数的获取：@RequestHeader
query-->请求参数的获取：@RequestParam
path（用于restful接口）-->请求参数的获取：@PathVariable
body（不经常使用）
form（不经常使用）
name：参数名
dataType：参数类型
required：参数是否必须传
value：参数的意思
defaultValue：参数的默认值
@ApiResponses：用于表示一组响应
@ApiResponse：用在@ApiResponses中，通常用于表达一个错误的响应信息
code：数字，例如400
message：信息，例如"请求参数没填好"
response：抛出异常的类
@ApiModel：描述一个Model的信息（这种通常用在post建立的时候，使用@RequestBody这样的场景，请求参数没法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：描述一个model的属性

5.启动服务 ，直接访问 “http://localhost:8080/swagger-ui.html”便可（这个是带Ui界面的）

还有一个地址是：http://localhost:8080/v2/api-docs

github 地址：https://github.com/tuonioooo/Spring/tree/ca1dc6344ce9b9c892bb1e0284e946dc0189f966/Spring-boot/swagger-example