Swagger-Lazydoc版本更新-API文档管理UI介绍及使用

swagger版本更新

待实现功能列表
支持API 测试用例 Mock功能
云服务端支持多用户
云服务端支持开放API管理
支持导出swagger PDF或者HTML文档

swagger-lazydoc v1.0.2
测试用例响应JSON字符串超长自动换行
增加本地权限控制
增加云登录权限控制
增加云服务端管理
增加测试用例保存功能

swagger-lazydoc v1.0.0
项目初始化构想设计
优化文档管理界面风格
测试用例页面增加格式化响应报文
测试用例页面增加响应头信息

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

API接口防恶意调用盗链或攻击方案

Web前后分离开发,防止API接口被恶意调用或攻击。度娘分享了很多种应对场景的方法。总结得比较好的见文章《前后端分离,如何防止API接口被恶意调用或攻击》、《如何防止别人恶意调用API接口》。
网络安全
本文选用了另外一种常见的配置下载防盗链机制的方法,使用该方式前请仔细阅读《彻底搞清referrer和origin》后,理解应用场景。具体操作记录如下:

  1. 增加Nginx端配置,使其能够获取到Http头信息Origin、Referer。
    proxy_set_header Origin $http_origin;
    proxy_set_header Referer $http_referer;
    
  2. 后端Java来源验证
    public static boolean originAuth(HttpServletRequest request) {
            String referer = request.getHeader("Referer");
            String origin = request.getHeader("Origin");
            String sitePart = request.getServerName();
            if(referer == null || origin == null) {
                return false;
            }
            if (referer != null && !referer.contains(sitePart)) {
                return false;
            }
            if (origin != null && !origin.contains(sitePart)) {
                return false;
            }
            return true;
        }
    

因Http协议是无状态的,针对上面的方法也不是完全无破解方案,只是提高了攻击者的难度。在这条接口网络安全的道路上还得持续的斗智斗勇。