Swagger 接口文档开发示例

Maven依赖

根据代码生成文档
（必须）swagger2

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
            <exclusions>
                <exclusion>
                    <groupId>io.swagger</groupId>
                    <artifactId>swagger-models</artifactId>  
                    //默认1.5.20版本，会出现类型转换异常问题，排除该版本，引入1.5.22版本
                </exclusion>
            </exclusions>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.22</version>
        </dependency>

图形界面选择
（二选其一）springfox-swagger-ui

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>

（二选其一）swagger-bootstrap-ui

        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.5</version>
        </dependency>

接口文档页面的访问方式

springfox-swagger-ui

项目ip:端口/swagger-ui.html    示例：localhost:8080/swagger-ui.html

swagger-bootstrap-ui

项目ip:端口/doc.html    示例：localhost:8080/doc.html

配置类示例

@Configuration
@EnableSwagger2
public class SwaggerConfig {
/**
 * @Description api首页信息
 * @Param []
 * @return springfox.documentation.service.ApiInfo
 **/
	private ApiInfo apiInfo() {
		Contact contact = new Contact("作者", "作者网上主页", "作者邮箱");
		return new ApiInfo("接口title", //主要
				"这是一个测试描述",  //主要
				"版本",
				"服务链接",
				contact,
				"许可",
				"许可链接",
				new ArrayList<>()
				);
	}

	@Bean
	public Docket docket() {
		/*
		 *  全局配置信息（可以不用）
		 */
		Parameter token = new ParameterBuilder().name("token")
				.description("用户令牌")
				.parameterType("header")
				.modelRef(new ModelRef("String"))
				.build();
		List<Parameter> parameters = new ArrayList<>();
		parameters.add(token);
		
		return new Docket(DocumentationType.SWAGGER_2)
				.globalOperationParameters(parameters)  //传入全局配置
				.apiInfo(apiInfo())  //传入api首页信息
				.select() //进行筛选
				//通过package筛选，
				.apis(RequestHandlerSelectors.basePackage("com.example.controller"))
				//构建api
				.build();
	}

}

Controller示例

@Api(tags = "用户管理相关接口UserController")
@RestController
@RequestMapping("/user")
public class UserController {
	@ApiOperation("获取用户信息")
	@ApiImplicitParams(
		{
			@ApiImplicitParam(name = "username",
					value = "用户名",
					dataType = "String",
					required = true
			),
			@ApiImplicitParam(name = "password", value = "用户密码",dataType = "String",required = true)
		}
	)
	@PutMapping("/updateUser")
	public String updateUser(String username,String password) {
		return username+","+password;
	}

	@PostMapping("/addUser")
	public User addUser(@RequestBody User user) {
		return user;
	}
	@GetMapping("/getUser")
	public String getUser(){
		return "gcl";
	}
	@DeleteMapping("/deleteUser")
	public String deledteUser(){
		return "删除";
	}

实体类示例

/*
	@ApiModel 对实体类生成文档
*/
@ApiModel
/*
	@Data lombok插件,可以不选，那就需要手动生成构造方法和get，set方法
*/
@Data
public class User {
	/*
		@ApiModelProperty 对属性进行配置
	*/
	@ApiModelProperty(value = "用户id ",name = "idName",required = true)
	private int id;
	@ApiModelProperty(value = "用户名称 ",name = "nameName",required = true)
	private String name;
	@ApiModelProperty(value = "用户年龄 ",name = "ageName",required = true)
	private int age;
}

后记

忽略
通过@ApiIgnore 放在类前或方法前，则不扫描该类或方法

通过RequestHandlerSelectors筛选
RequestHandlerSelectors配置筛选规则
有五个方法

any() //所有
none() //无
withMethodAnnotation() //按照方法上的注解
withClassAnnotation()  //按照类上的注解
basePackage() //按照包扫描

使用方法

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

通过PathSelectors筛选
四个方法

any() //所有
none() //不扫描
regex() //正则
ant() //ant路径

使用方法

.paths(PathSelectors.ant("/user/**"))