• 欢迎访问ByWei.Cn,推荐使用最新版火狐浏览器和Chrome浏览器访问本网站,加入百味博客 QQ群
  • 已升级为最新版主题,并将持续优化改造中,支持说说碎语功能,可像添加文章一样直接添加说说,博客主题升级啦
  • 感谢您百度求点赞啊!百度网址
  • 如果您觉得本站非常有看点,那么赶紧使用Ctrl+D 收藏百味博客吧
  • 博主热烈欢迎 软件定制开发 联系:http://www.bywei.cn

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

开源软件 bywei 5个月前 (05-28) 3289次浏览 2个评论 扫描二维码

在介绍 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://oss.sonatype.org/content/groups/staging/cn/bywei/

<dependency> 
 <groupid>cn.bywei</groupid> 
 <artifactid>swagger-lazydoc-ui</artifactid>
 <version>1.0.2</version> 
</dependency>

 

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&lt;String&gt; 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

百味博客 , 版权所有丨如未注明 , 均为原创丨本网站采用BY-NC-SA协议进行授权
转载请注明原文链接:swagger-lazydoc-ui 在线文档管理利器-API 接口文档自动生成
喜欢 (1)
[微信扫一扫]
分享 (0)
发表我的评论
取消评论

表情 贴图 加粗 删除线 居中 斜体 签到

Hi,您需要填写昵称和邮箱!

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址
(2)个小伙伴在吐槽
  1. 写的真不错,能学到很多东西!
    图床2019-06-17 17:08 回复