swagger-lazydoc-ui 在线文档管理利器-API接口文档自动生成

在介绍API在线文档管理工具swagger-lazydoc-ui之前，不得不先简单介绍一下其依赖的强大的一款RESTFUL接口的文档在线自动生成+功能测试功能软件Swagger UI。

概述

在常规的开发过程中，经常会使用word的形式编写响应的API接口请求响应接口报文的描述说明文档，俗称API接口文档.相信大部分的研发同学都苦于编写文档的繁琐、大材小用了。也经常在接口更新之后懒于在更新word文档。特别是在项目需求变化越来越频繁，接口维护增加越来越多的情况一下，常规的文档管理的方式已经不利于现状。再加上现今前后端分离方式，合作协调开发等等场景。

为了解决上述描述的问题，Swagger UI应运而生。

Swagger UI可以让我们把定义的接口以配置文件或者代码注解的方式编写，最后生成一个可视化较高的网站。在开发过程中随手而写的注释时，就已经把文档编写完成了。如此强大的工具，如果你还没引进，继续阅读下文，将对你的工作提升十倍的效率。

安装部署

1、引入jar包

首先需要在你的 pom.xml 中引入swagger的包, 相关jar已发布在maven中央仓库上，或者直接下载jar 
swagger-lazydoc jar Maven仓库：https://mvnrepository.com/artifact/cn.bywei

    cn.bywei
    swagger-lazydoc-ui
    1.0.2

2、添加swagger自定义配置文件信息

spring boot项目在配置文件中根据具体需求添加如下内容

#swagger lazydoc config
#配置是否启用swagger lazydoc生成文档
swagger.lazydoc.enable=true
#配置生成的swagger lazydoc文档版本
swagger.lazydoc.version=2.0
#文档展示标题
swagger.lazydoc.title=swagger lazydoc apis
#文档展示描述信息
swagger.lazydoc.description=swagger lazydoc Project!
#文档联系人
swagger.lazydoc.contact.name=ByWei.Cn
#文档联系网址
swagger.lazydoc.contact.url=http://swagger-lazydoc.bywei.cn
#文档联系邮箱
swagger.lazydoc.contact.mail=master@bywei.cn
#生成文档包路径
swagger.lazydoc.basePackage=cn.bywei.api.controller
#是否启用权限验证,为true则必须验证后登录,并配置本地权限验证用户名密码
swagger.lazydoc.auth=true
#开启本地权限验证swagger.lazydoc.auth=true后,登录用户名
swagger.lazydoc.username=lazydocuser
#开启本地权限验证swagger.lazydoc.auth=true后,登录密码
swagger.lazydoc.password=lazydocpwd123
#配置云服务地址(非必须)，可下载开源代码自定义部署
swagger.lazydoc.cloudUrl=http://swagger-lazydoc.bywei.cn/cloud

3、启用swagger

• spring boot项目启动项添加@EnableSwaggerLazydoc：

  import org.springframework.boot.SpringApplication;
  import org.springframework.boot.autoconfigure.SpringBootApplication;
  
  import cn.bywei.swaggerlazydoc.core.EnableSwaggerLazydoc;
  
  @SpringBootApplication
  @EnableSwaggerLazydoc
  public class SwaggerlazydocTestApplication {
  
      public static void main(String[] args) {
          SpringApplication.run(SwaggerlazydocTestApplication.class, args);
      }
  }
  
  

• spring-mvc注入Bean：

  @Configuration
  @EnableSwaggerLazydoc
  @EnableWebMvc
  public class SwaggerLazydocConfig {
  }
  

4、添加swagger注解

常用的swagger注解如下，具体可以参考swagger官方注解文档：http://docs.swagger.io/swagger-core/apidocs/index.html

示例Controller方法

 @ApiOperation(value = "发送邮箱验证码",notes ="type类型和mail邮箱地址为必传项" )
 @RequestMapping(value = "/sendValidateCodeForMail",method = RequestMethod.POST)
 public BaseResponse<String> sendValidateCodeForMail(
 @RequestBody @ApiParam(name="发送邮件验证码对象",value="传入json格式",required=true)
 SendValidateCodeForMailReq req){
     ...
 return null;
 }

示例请求参数SendValidateCodeForMailReq 注解, 响应对象注解类似

@ApiModel(value="SendValidateCodeForMailReq",description="发送邮箱验证码请求对象")
public class SendValidateCodeForMailReq {
    @ApiModelProperty(value="验证类型 1：忘记密码验证码  2：新用户校验邮箱",name="type",required=true,example="1")
    private int type;	
    @ApiModelProperty(hidden=true)
    private String mebid;
    @ApiModelProperty(value="邮箱地址",name="mail",required=true)
    private String mail; 
    @ApiModelProperty(value="语言类型  LANG_ZH:中文 LANG_EN:英文",name="language")
    private LanguageTypeEnum  language;

    ... 

5、查看API接口文档

swagger-lazydoc-ui 的默认访问地址是：

http://${host}:${port}/swagger-lazydoc.html

开源地址

swagger lazydoc github :

https://github.com/bywei/SwaggerLazydoc

喜欢 (6)赏

[微信扫一扫]

分享 (0)