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

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

概述

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

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

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

Swagger官网:http://swagger.io
Swagger官方描述:The World’s Most Popular Framework for APIs.

Swagger ui 的原生UI管理界面如下:

swagger-ui

关于swagger-lazydoc-ui

swagger-ui-layer针对原生的UI显示重新进行了设计,以使界面更加符合文档的管理方式,在请求和响应描述处使用表格展示的形式比原生的UI更加直观, 在此感谢swagger-ui-layer作者提供了Swagger 自定义UI界面方案。
在此基础上做了部分改进,SpringMVC/Springboot实战集成Swagger2, 后期还在持续更新中,本章可作为Swagger入门教程。具体进度将抽时间更新该文章:

  • 优化文档管理界面的风格样式
  • 解决文档展示信息的不全引起的bug
  • 增加接口调试相关的头信息
  • 增加接口调试信息的记录
  • 增加云端拆分部署的方式
  • 增加接口数据的Mock

其他功能还在持续优化进行中,欢迎提供建议或意见

当前的效果图如下:

swagger-lazydoc-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

Annotation Type Description
Api
Marks a class as a Swagger resource.
ApiImplicitParam
Represents a single parameter in an API Operation.
ApiImplicitParams
A wrapper to allow a list of multiple ApiImplicitParam objects.
ApiModel
Provides additional information about Swagger models.
ApiModelProperty
Adds and manipulates data of a model property.
ApiOperation
Describes an operation or typically a HTTP method against a specific path.
ApiParam
Adds additional meta-data for operation parameters.
ApiResponse
Describes a possible response of an operation.
ApiResponses
A wrapper to allow a list of multiple ApiResponse objects.
Authorization
Declares an authorization scheme to be used on a resource or an operation.
AuthorizationScope
Describes an OAuth2 authorization scope.

示例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

“swagger-lazydoc-ui 在线文档管理利器-API接口文档自动生成”的2个回复

图床进行回复 取消回复

电子邮件地址不会被公开。 必填项已用*标注

4 × 1 =

此站点使用Akismet来减少垃圾评论。了解我们如何处理您的评论数据