在线API
百度已收录

       无论是前端还是后端开发,都或多或少地被接口文档折磨过。前端经常抱怨后端给的接口文档与实际情况不一致。后端又觉得编写及维护接口文档会耗费不少精力,经常来不及更新。其实无论是前端调用后端,还是后端调用后端,都期望有一个好的接口文档。采用传统的编写接口文档的方式,随着时间推移,版本迭代,接口文档往往很容易就跟不上代码了。云程平台采用Swagger,可以省略了这一步,而且文档出错率近乎于零, 只要你在写代码的时候,稍加几个注解,文档自动生成。

         通过Swagger接口规范,你只需要按照它的规范去定义接口及接口相关的信息。再通过Swagger衍生出来的一系列项目和工具,就可以做到生成各种格式的接口文档,生成多种语言的客户端和服务端的代码,以及在线接口调试页面等等。这样,如果按照新的开发模式,在开发新版本或者迭代版本的时候,只需要更新Swagger描述文件,就可以自动生成接口文档和客户端服务端代码,做到调用端代码、服务端代码以及接口文档的一致性。

        作为Java届服务端的大一统框架Spring,迅速将Swagger规范纳入自身的标准,建立了Spring-swagger项目,后面改成了现在的Springfox。通过在项目中引入Springfox,可以扫描相关的代码,生成该描述文件,进而生成与代码一致的接口文档和客户端代码。这种通过代码生成接口文档的形式,在后面需求持续迭代的项目中,显得尤为重要和高效。

 

一、通过swagger注解定义接口

1、在控制层Controller中添加注解来描述接口信息,以职务管理模块为例说明:

@RestController
@Api(tags = "职务管理接口")
@RequestMapping("/system/sysPosition")
public class SysPositionController extends BaseController<SysPosition, ISysPositionService> {
   private static final Logger log = LoggerFactory.getLogger(SysPositionController.class);
   @Autowired
   private ISysPositionService sysPositionService;
   
   @GetMapping(value = "/list")
   //@RequiresPermissions("system:SysPosition:query")
   @AutoLog(value = "职务管理-分页查询")
   @ApiOperation(value = "职务管理-分页查询", notes = "职务管理-分页查询")
   public HttpResult<?> queryPageList(SysPosition sysPosition,
                                          @RequestParam(name="pageNo", defaultValue="1") Integer pageNo,
                                          @RequestParam(name="pageSize", defaultValue="10") Integer pageSize,
                                          HttpServletRequest req) {
      QueryWrapper<SysPosition> queryWrapper = QueryBuilder.initQueryWrapper(sysPosition, req.getParameterMap());
      Page<SysPosition> page = new Page<SysPosition>(pageNo, pageSize);
      IPage<SysPosition> list = sysPositionService.page(page, queryWrapper);
      return HttpResult.ok(list);
   }


   @PostMapping(value = "/add")
   @RequiresPermissions("system:SysPosition:add")
   @AutoLog(value = "职务管理-添加")
   @ApiOperation(value = "职务管理-添加", notes = "职务管理-添加")
   public HttpResult<?> add(@RequestBody SysPosition sysPosition) {
      sysPositionService.save(sysPosition);
      return HttpResult.ok(I18nUtil.message("save.success"));
   }
}

2、在model类上添加注解来描述接口信息:

@ApiModel(value = "职务管理对象", description = "职务管理对象")
@TableName("sys_position")
public class SysPosition extends BaseEntity implements Serializable {
    private static final long serialVersionUID = 1L;

   /**职位名称*/
   @Excel(name = "职位名称", width = 15)
   @ApiModelProperty(value = "职位名称")
   private java.lang.String positionName;
   /**职位编码*/
   @Excel(name = "职位编码", width = 15)
   @ApiModelProperty(value = "职位编码")
   private java.lang.String positionCode;
   /**职位排序*/
   @Excel(name = "职位排序", width = 15)
   @ApiModelProperty(value = "职位排序")
   private java.lang.Integer positionOrder;
   /**职位描述*/
   @Excel(name = "职位描述", width = 15)
   @ApiModelProperty(value = "职位描述")
   private java.lang.String description;
}

经常使用的swagger注解有:

作用范围

API注解

使用位置

协议集描述

@Api

用于controller类上

对象属性

@ApiModelProperty

用在出入参数对象的字段上

协议描述

@ApiOperation

用在controller的方法上

Response集

@ApiResponses

用在controller的方法上

Response

@ApiResponse

用在 @ApiResponses里边

非对象参数集

@ApiImplicitParams

用在controller的方法上

非对象参数描述

@ApiImplicitParam

用在@ApiImplicitParams的方法里边

描述返回对象的意义

@ApiModel

用在返回对象类上

更详细的使用方法请参考:https://www.cnblogs.com/three-fighter/p/12346184.html

 

二、通过在线接口管理查看API