SpringBoot中使用Swagger生成RestFul规范API文档

1. 在pom.xml文件中添加依赖

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

2. 创建swagger配置类

package com.bitzh.config;


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.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

/**
 * Swagger 配置文件
 */
@Configuration      //标记为配置类
@EnableSwagger2     //开启swagger
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.bitzh.controller"))
                //basePackage可以指定生成api的包,指定的包下面的controller类中的requestMapping方法会生成api解释
                .paths(PathSelectors.any())
                .build();
    }

    //配置封面信息
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("图书管理系统接口文档")            //封面标题
                .description("此文档描述了****")         //文档描述
                .contact(new Contact("张三","www.abc142162.com","z5123451@163.com"))  //联系人
                .version("1.0")     //版本号
                .build();
    }
}

封面效果

3. 为controller、requestMapping方法及其中的参数添加详细解释

package com.bitzh.controller;


import com.bitzh.entity.User;
import com.bitzh.service.UserService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.*;

import javax.annotation.Resource;

@RestController
@Api(tags = "用户信息管理接口")
public class UserController {

    @Resource
    private UserService userService;


    @RequestMapping(value = "/test/{id}",method = RequestMethod.GET)
    @ApiOperation(value = "根据ID查询用户",notes = "根据ID查询用户，返回用户对象")
    @ApiImplicitParam(name = "id",value = "用户ID",required = true,dataType = "int")
    public User getUser(@PathVariable("id") int userId){
        User user = userService.queryUserByUserId(userId);
        return user;
    }

    @GetMapping("/test/{userId}/{userName}")
    @ApiOperation(value = "打印用户信息",notes = "打印出用户的ID和用户名")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "userId",value = "用户ID",required = true,dataType = "int"),
            @ApiImplicitParam(name = "userName",value = "用户名",required = true,dataType = "string")
    })
    public void printUser(@PathVariable("userId") int userId,@PathVariable("userName") String userName){
        System.out.println(userId+userId);
    }
}

实现效果

4. 为实体类添加详细描述

package com.bitzh.entity;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import lombok.Data;

/**
 * 对实体对象添加详细描述
 */
@Data
@ApiModel(value = "user对象",description = "用户信息")
public class User {
    @ApiModelProperty(value = "用户ID",dataType = "int",required = true)
    private int userId;
    @ApiModelProperty(value = "用户名",dataType = "string",required = true)
    private String userName;
    @ApiModelProperty(value = "用户密码",dataType = "string",required = true)
    private String userPwd;
    @ApiModelProperty(value = "盐",dataType = "string")
    private String pwdSalt;
}

实现效果

启动服务器，访问：http://localhost:8080/swagger-ui.html
获取生成的api文档

常用类解释

1. @Api
用在controller上，说明该controller的作用
@Api(value = "用户信息管理接口")

2. @ApiOperation
用在方法上，说明方法的作用
@ApiOperation(value = "根据ID查找用户", notes = "调用此接口的注意事项", httpMethod = "GET")

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

@ApiImplicitParams({
@ApiImplicitParam(name = "userId",value = "用户ID",required = true,dataType = "int"),
@ApiImplicitParam(name = "userName",value = "用户名",required = true,dataType = "string")

})

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

paramType：参数放在哪个地方

header（参数放在请求头中）–>请求参数的获取：@RequestHeader
query（参数放在url中，例如findUser.action?userId=1）–>请求参数的获取：@RequestParam
path（用于restful接口，例如/user/1）–>请求参数的获取：@PathVariable

name：参数名
dataType：参数类型
required：参数是否必须传
value：参数的意思
defaultValue：参数的默认值

5. @ApiModel
描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用@ApiImplicitParam注解进行描述的时候），例如

@ApiModel(value = "用户实体类",description = "用户信息")
public class User {
}

6. @ApiModelProperty
描述一个model的属性，例如

@ApiModelProperty(value = "用户ID",dataType = "int",required = true)
private int userId;