使用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 整形

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

上一篇:C#跨平台应用开发进展(2020-07-20)


下一篇:C#从入门到放弃—日期操作