接口文档swagger（Swagger离线文档生成）

本文目录

• Swagger离线文档生成
• swagger-ui及swagger用法
• Swagger常见注解@API、@ApiOperation、@ApiParam等
• Springboot2.X版本配置Swagger2
• Swagger接口文档

Swagger离线文档生成

离线接口文档自动生成器 适用范围： 将标准的swagger.json文件解析并转换成一定格式的接口文档，其中文档的章节排序可以在index.adoc中自定义排序。生成的接口文档有html和pdf格式两种，由于插件转换中文需要特殊配置，默认生成的含中文的文档存在一定字体错乱，所以建议使用html格式文档。Html格式文档可以使用word打开，并转换成其他格式。 操作步骤： 1.      将ConvertSwagger.rar解压出来 2.      修改\ConvertSwagger\src\docs\asciidoc文件夹下面的index.adoc与manual_content.adoc,manual_content.adoc。index.adoc中可以将manual_content.adoc添加进去：并在manual_content.adoc中添加自定义描述内容： （可选）3.      在\ConvertSwagger\target\swagger中添加swagger.json文件4.      编译此工程 在ConvertSwagger目录中 mvn package5.      在\ConvertSwagger\target\asciidoc\html中拿到html格式的接口文档，自动生成的文档名称默认是index.html。

swagger-ui及swagger用法

默认的swagger-ui好用但是不够美观，为了让生成的文档更加可观，我们可以使用swagger-ui-layer 来美化。 swagger-ui-layer，基于layui 开源的swagger-ui的替换。界面大气，使用起来也很方便。swagger-ui-layer 依于swagger的功能，所以在原先项目中导入以下依赖即可 注意： 使用规则： 一、在返回对象类上中要使用注解@ApiModel(value="实体类对象", description="实体类描述")，对象字段上使用@ApiModelProperty(value=”字段说明“,required=”是否必填”)表示对model属性的说明 注意：@ApiModel value 不能同名，否则会导致参数乱窜. 二、@API使用在Controller类上，表明是swagger资源 @Api(value = "仓库管理controller", tags = {"仓库管理接口"}) ***隐藏网址*** 四、 @RequestBody和@ApiImplicitParam不能共用 @RequestBody主要用来接收前端传递给后端的json字符串中的数据的，如果想要swagger显示出实体类的参数描述信息要在实体类上使用@ApiModel(value="") 原先：在接口方法中会使用@ApiImplicitParam(name = "vo", value = "用户实体类", paramType = "body", required = true, dataType = "UserVo") 但@RequestBody和@ApiImplicitParam注解，会使实体类参数描述信息显示不出来，所以@ApiImplicitParam适用于没有接收实体类参数的方法 五、 @ApiParam 用于 Controller 中方法的参数说明。如图所示。 六、如果接口中，实体参数的描述没有显示出来可以加上@ModelAttribute 注解 七、通过 @PathVariable 可以将 URL 中占位符参数绑定到控制器处理方法的入参中：URL 中的 {xxx} 占位符可以通过@PathVariable(“xxx“) 绑定到操作方法的入参中。在swagger接口文档中，不会显示出这个占位符的具体信息，如下不会显示出这个id的说明 建议使用@ApiParam注解： 也可以使用@ApiImplicitParam对接收的参数进行解释 注意： 要改成这样 八、在使用@RequestParam注解，获得前台传递的值，一般要结合@ApiParam注解使用

Swagger常见注解@API、@ApiOperation、@ApiParam等

Swagger2一些常用注解 最近遇到了一个使用swagger来生成接口文档的项目，在controller看到了一些没用过的注解（@API、@ApiOperation等），遂记录一下 @API 使用在类上，表明是swagger资源，@API拥有两个属性:value、tags，源码如下 //If tags is not used,this value will be used to set the tag for the operations described by this resource. Otherwise, the value will be ignored. String value() default ""; //Tags can be used for logical grouping of operations by resources or any other qualifier. String tags() default {""}; 1 2 3 4 5 生成的api文档会根据tags分类，直白的说就是这个controller中的所有接口生成的接口文档都会在tags这个list下；tags如果有多个值，会生成多个list，每个list都显示所有接口 @Api(tags = "列表1") @Api(tags = {"列表1","列表2"}) 1 2 value的作用类似tags,但是不能有多个值 @ApiOperation ***隐藏网址*** 源码中属性太多，记几个比较常用 value用于方法描述 notes用于提示内容 tags可以重新分组（视情况而用） @ApiParam 使用在方法上或者参数上，字段说明；表示对参数的添加元数据（说明或是否必填等） name–参数名 value–参数说明 required–是否必填 @ApiModel() 使用在类上，表示对类进行说明，用于参数用实体类接收 value–表示对象名 description–描述 @ApiModelProperty() 使用在方法，字段上，表示对model属性的说明或者数据操作更改 value–字段说明 name–重写属性名字 dataType–重写属性类型 required–是否必填 example–举例说明 hidden–隐藏

Springboot2.X版本配置Swagger2

为什么要引入Swagger? 有过后台开发和前端联调的人都会被接口文档折磨，更新不及时，文档和代码不一致，无法调试，swagger就是为了解决这个问题。 看下swagger官方介绍 Swagger是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。总体目标是使客户端和文件系统作为服务器以同样的速度来更新。文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。 如此好的利器，怎么在后台框架中快速集成呢？ 第一步、添加maven依赖 需要在系统的pom中添加如下依赖： 第二步、添加swagger配置文件 第三步、测试 ***隐藏网址***总结 很好用的开源框架，集成也很简单，建议大家在工程中使用，能够快速开发，减少前后端沟通api的时间成本。

Swagger接口文档

@ApiOperation(value = "分页查询用户", notes = "" + "部分机密的查询字段、返回字段需要另外申请授权；\n" + "【关键字段】提示（详见字段备注）：\n" + "1、判断用户是否失效，status;\n" + "2、获取用户所在组织，directDepartId;如果需要获取用户所在部门或系统，自行实现：根据部门全路径以及每个部门的级别判断\n" + "【信息安全】提示：\n" + "1、用户邮箱、手机、教育、职级等个人敏感消息请勿泄露给普通用户\n" + "此接口可提供的【功能示例】：\n" + "1、【根据多个工号查询用户】，必要参数usernames;\n" + "2、【根据部门查询用户】，必要参数departmentId（部门ID），不包含子组织\n" + "其他1、【全量同步用户】，只用于初始化用户数据，先查出所有部门，再按部门查询用户\n" + "其他2、【增量同步用户】，对接消息推送服务，对接文档：" ) @ApiImplicitParams(value = { @ApiImplicitParam(name = "pageIndex", value = "页码,默认1", paramType = "query", defaultValue = "1"), @ApiImplicitParam(name = "pageSize", value = "页大小,最大2000，默认10", paramType = "query", defaultValue = "10")})