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

swagger版本更新

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

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

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

HTTP Basic Authorization身份认证模式,抢先认证HttpClient 4.5.3 实例

Basic认证

关于HTTP BASIC认证

Basic 认证是服务器与客户端之间进行认证的一种方式,最初是在HTTP 1.0 规范(RFC 1945)中定义,后续的有关安全的信息可以在HTTP 1.1规范(RFC 2616)和HTTP认证规范(RFC 2617)中找到。HTTP Basic Authentication认证的服务,需要提供用户名和密码,否则服务器就会返回401。

HTTP BASIC认证流程原理

HTTP使用BASIC认证的原理是在HTTP协议进行通信的过程中,HTTP协议定义了基本认证过程以允许HTTP服务器对WEB浏览器进行用户身份认证的方法。
实现方法:当一个客户端向HTTP服务器进行数据请求时,如果客户端未被认证,则HTTP服务器将通过基本认证过程对客户端的用户名及密码进行验证,以决定用户是否合法。客户端在接收到HTTP服务器的身份认证要求后,会提示用户输入用户名及密码, 用户输入后,客户端将用户名和密码中间用“:”分隔合并,并将合并后的字符串用BASE64编码,在每次请求数据 时,将密文附加于请求头(Request Header)Authorization: Basic XXXXXXX中。HTTP服务器在每次收到请求包后,根据协议取得客户端附加的用户信息(BASE64编码的用户名和密码),解开请求包,对用户名及密码进行验证,如果用 户名及密码正确,则根据客户端请求,返回客户端所需要的数据;否则,返回错误代码或重新要求客户端提供用户名及密码。

JAVA HttpClient 4.5.3 抢先认证实例

原HttpClient 4.1.1 实例方法DefaultHttpClient等已过时废弃, 如下测试实例中,实现了两种方法:
1)通过HttpClient提供的抢先认证方式,直接跳过验证是否登录,把Basic Authorization信息发送给服务器
2)直接添加header的方式,HttpClient抢先认证方式原理同理

import java.io.IOException;
import java.nio.charset.Charset;
import java.util.Base64;

import org.apache.http.HttpEntity;
import org.apache.http.HttpHost;
import org.apache.http.auth.AuthScope;
import org.apache.http.auth.UsernamePasswordCredentials;
import org.apache.http.client.AuthCache;
import org.apache.http.client.CredentialsProvider;
import org.apache.http.client.config.RequestConfig;
import org.apache.http.client.methods.CloseableHttpResponse;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.protocol.HttpClientContext;
import org.apache.http.entity.ContentType;
import org.apache.http.impl.auth.BasicScheme;
import org.apache.http.impl.client.BasicAuthCache;
import org.apache.http.impl.client.BasicCredentialsProvider;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClientBuilder;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.protocol.BasicHttpContext;
import org.apache.http.protocol.HttpContext;
import org.apache.http.util.EntityUtils;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;

@RunWith(SpringJUnit4ClassRunner.class)
public class HttpsClientTest {

	@Test
	public void test_auth_basic_should_success() throws Exception {
		String url ="http://192.168.1.100:8080/bywei/api/authtest";
		HttpHost targetHost = new HttpHost("192.168.1.100", 8080, "http");
		HttpGet get = new HttpGet(url);
		UsernamePasswordCredentials credentials = new UsernamePasswordCredentials("test-auth", "=^ad.*sa:_2_RXa*23");
		
		// 使用 AuthCache 方式将使用RestClient 中的 MainClientExec方法,在发送请求时直接携带Authorization header信息
    	       AuthCache authCache = new BasicAuthCache();
    	       // Generate BASIC scheme object and add it to the local auth cache
    	      BasicScheme basicAuth = new BasicScheme();
    	      authCache.put(targetHost, basicAuth);
    	      // Add AuthCache to the execution context
    	      BasicHttpContext localcontext = new BasicHttpContext();
    	      localcontext.setAttribute(HttpClientContext.AUTH_CACHE, authCache);
		
		String content = doExecute(get, targetHost, credentials, localcontext);
		System.out.println("Authorization Basic认证authCache请求响应:"+content);
	}
	
	@Test
	public void test_auth_header_should_success() throws Exception {
		String url ="http://192.168.1.100:8080/bywei/api/authtest";
		HttpHost targetHost = new HttpHost("192.168.1.100", 8080, "http");
		HttpGet get = new HttpGet(url);
		String token = "test-auth:=^ad.*sa:_2_RXa*23";
		byte[] auth = Base64.getEncoder().encode(token.getBytes("UTF-8"));
		get.addHeader("Authorization", "Basic " + new String(auth));
		HttpClientContext context = HttpClientContext.create();
		String content = doExecute(get, targetHost, null, context);
		System.out.println("Authorization Basic认证header请求响应:"+content);
	}
	
	private CloseableHttpClient getHttpClient(UsernamePasswordCredentials credentials){
	    RequestConfig requestConf = RequestConfig.custom().setAuthenticationEnabled(false).build();
	    HttpClientBuilder httpClientBuilder = HttpClients.custom();
	    if(credentials != null) {
	    	CredentialsProvider provider = new BasicCredentialsProvider();
	    	provider.setCredentials(AuthScope.ANY, credentials);
	    	httpClientBuilder.setDefaultCredentialsProvider(provider);
	    }
	    CloseableHttpClient client = httpClientBuilder.setDefaultRequestConfig(requestConf).build();
	    return  client;
	}
	
	private String doExecute(HttpGet get, HttpHost targetHost, UsernamePasswordCredentials credentials, HttpContext contenxt) throws Exception {
		CloseableHttpResponse response = null;
		String content = "";
        try {
        	
        	//指定Client使用HttpContext,包含属性:http.auth.auth-cache
            response = getHttpClient(credentials).execute(get, contenxt);
            HttpEntity entity = response.getEntity();
            if(entity!=null) {
                Charset charset = ContentType.getOrDefault(entity).getCharset();
                content = EntityUtils.toString(entity, charset);
                EntityUtils.consume(entity);
                return content;
            }
        } catch(Exception ie) {
            ie.printStackTrace();
            throw ie;
        } finally {
            try {
                if(response!=null) {
                    response.close();
                }
            } catch(IOException e) {
            }
            if(get!=null) {
            	get.releaseConnection();
            } 
        }
        return content;
	}
}

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