使用Swagger2生成API文档实现前后端分离交互

1：简介

你还在为编写高质量API而苦恼吗？你还在为随时更新而烦躁吗？你还在为专门的测试工具而安装软件吗？Swagger2来帮你！！

你只需要添加必要的注解，Swagger2会自动生成Restful 风格的API文档。并且及时更新，代码变化，文档也随之变化。

提供了统一的测试环境，方便调试

2：使用

1：导入依赖

    <!--swagger2的jar包-->

        <dependency>

            <groupId>io.springfox</groupId>

            <artifactId>springfox-swagger2</artifactId>

            <version>2.9.2</version>

        </dependency>

        <!--引入视觉的样式的UI-->

        <dependency>

            <groupId>io.springfox</groupId>

            <artifactId>springfox-swagger-ui</artifactId>

            <version>2.9.2</version>

        </dependency>

2：创建配置类

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket createRestApi() {

        return new Docket(DocumentationType.SWAGGER_2)
                .useDefaultResponseMessages(false)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(Api.class))//只生成被@Api修饰的类
//                .apis(RequestHandlerSelectors.withMethondAnnotation(ApiOperation.class))//只生成被@ApiOperation修饰的方法
                .paths(PathSelectors.any())
                .build();

}
//配置页面信息
@Bean
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("利用swagger构建api文档")//页面标题
                .description("简单使用swagger2")//本页面内容描述
                .version("1.0")
                .build();
    }

}

说明：

3：在Controller层中必要部分加注解

import com.reachauto.hkr.cxn.swagger.bean.ChangeRentalShopParameter;
import io.swagger.annotations.*;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.ui.ModelMap;
import org.springframework.web.bind.annotation.*;

import java.util.Date;

@Api(value = "API - VehiclesController", description = "车辆模块接口详情")
@RestController
@RequestMapping("/vehicles")
public class VehiclesController {

    private static Logger logger = LoggerFactory.getLogger(VehiclesController.class);


    @ApiOperation(value = "查询车辆接口", notes = "此接口描述xxxxxxxxxxxxx<br/>xxxxxxx<br>值得庆幸的是这儿支持html标签<hr/>", response = String.class)
    @ApiImplicitParams({
            @ApiImplicitParam(name = "vno", value = "车牌", required = false,
                    dataType = "string", paramType = "query", defaultValue = "辽A12345"),
            @ApiImplicitParam(name = "page", value = "page", required = false,
                    dataType = "Integer", paramType = "query",defaultValue = "1"),
            @ApiImplicitParam(name = "count", value = "count", required = false,
                    dataType = "Integer", paramType = "query",defaultValue = "10")
    })
    @ApiResponses(value = {
            @ApiResponse(code = 200, message = "Successful — 请求已完成"),
            @ApiResponse(code = 400, message = "请求中有语法问题，或不能满足请求"),
            @ApiResponse(code = 401, message = "未授权客户机访问数据"),
            @ApiResponse(code = 404, message = "服务器找不到给定的资源；文档不存在"),
            @ApiResponse(code = 500, message = "服务器不能完成请求")}
    )
    @ResponseBody
    @RequestMapping(value = "", method = RequestMethod.GET)
    public ModelMap findVehicles(@RequestParam(value = "vno", required = false) String vno,
                                 @RequestParam(value = "page", required = false) Integer page,
                                 @RequestParam(value = "count", required = false) Integer count)
            throws Exception {

        logger.info("http://localhost:8501/api/v1/vehicles");
        logger.info("## {},{},{}", vno, page, count);
        logger.info("## 请求时间：{}", new Date());

        ModelMap map = new ModelMap();
        map.addAttribute("vno", vno);
        map.addAttribute("page", page);
        return map;
    }
}

4：查看

http://localhost:8080/api/v1/swagger-ui.html

3：常用注解

注解	属性	值	备注
@Api	value	字符串	可用在class头上,class描述
	description	字符串
			@Api(value = "xxx", description = "xxx")
@ApiOperation	value	字符串	可用在方法头上.参数的描述容器
	notes	字符串	方法的备用说明
			@ApiOperation(value = "xxx", notes = "xxx")
@ApiImplicitParams	{}	@ApiImplicitParam数组	可用在方法头上.参数的描述容器
			@ApiImplicitParams({@ApiImplicitParam1,@ApiImplicitParam2,...})
@ApiImplicitParam	name	字符串 与参数命名对应	可用在@ApiImplicitParams里
	value	字符串	参数中文描述
	required	布尔值	true/false
	dataType	字符串	参数类型
	paramType	字符串	参数请求方式:query/path
			query:对应@RequestParam?传递
			path: 对应@PathVariable{}path传递
	defaultValue	字符串	在api测试中默认值
			用例参见项目中的设置
@ApiParam			单个参数描述
@ApiModel			用对象实体作为入参，实体类上使用
@ApiModelProperty			使用在被@ApiModel注解的模型类的属性上
@ApiProperty			用对象接收实体参数时，描述对象的一个字段
@ApiResponses	{}	@ApiResponse数组	可用在方法头上.参数的描述容器，HTTP相应整体描述
	code	数字	例如400,404
	message	信息	例如"请求参数没填好"
	response		抛出异常的类
@ApiResponse			HTTP响应其中1个描述，方法返回值的说明
@ApiIgnore			使用注解忽略这个API
@ApiError			发生错误返回的信息
@ApiImplicitParam			一个请求参数
@ApiImplicitParams			多个请求参数
	name		参数名
	value		参数的汉字说明，解释
	required		参数是否必须传
	paramType		参数放在哪个地方 · header --> 请求参数的获取：@RequestHeader · query --> 请求参数的获取：@RequestParam             · path（用于restful接口）--> 请求参数的获取：@PathVariable             · body（请求体）-->  @RequestBody User user             · form（普通表单提交）
	dataType		参数类型，默认String，其他值dataType=“int”
	defaultValue		参数的默认值
@ApiResponse	code	整形