Swagger 2(Open API v3.0) Java 文档生成指南(下)

版权声明:本文为博主原创文章,未经博主允许不得转载。 https://blog.csdn.net/zhangxin09/article/details/82707460

先介绍网上“搜刮”的资源:

和 Swagger UI 的集成

怎么把这些 API 信息漂亮地展示出来呢? 接下来我们通过集成 Swagger UI 来实现。首先是下载 Swargger UI,它是一个 react 写成的纯前端项目,可以集成到任意服务端中,只要让可以读取到 API 的定义文件即可,所以呢,哪怕是 file:// 打开也行,它会解析可以访问到的 yaml/json 文件,渲染漂亮的文档出来。

Swagger UI 不过就是 HTML+JS+CSS,到 https://github.com/swagger-api/swagger-ui/tree/master/dist 下载,注意是 dist 发布版本。如果你前端动手能力强,可以使用非 dist 版的,通过 webpack 等其他方案集成。但那样就不是和 Java Web 项目集成了,另外一个 web service 服务在跑。笔者为了省事,集成在当前 java 项目中,用 tomcat 跑。

但也要注意一下访问权限的问题,不能让所有人都访问,特别是包含敏感信息的接口。

下载回来,解压,发现源码包含 map 用于调试的,好几兆呢,我们不要,只要 HTML/JS/CSS 便可。

这里写图片描述
运行一下,没毛病呢。

这里写图片描述
默认是 PetStore 的,打开 index.html 修改之。
这里写图片描述
修改为本地的即可。

是不是觉得很简单呢?还有很多好玩的,例如转换为 markdown,就要看看 swagger2markup https://blog.csdn.net/qq_34368762/article/details/79129303

配置文件 openapi.yaml

配置文件 openapi.yaml 默认放在 classpath 中,才可以被读取。官方另外提供几种途径来编写 Swagger 的配置文件,这里就是不赘述了。
下面是配置文件的一个例子。

resourcePackages:
- com.foo.controller
prettyPrint: true
cacheTTL: 0

openAPI:
  info:
    version: '1.0'
    title: 无忧在线 API
    description: 'HTTP + JSON 接口,接口需要 token'
    termsOfService: http://swagger.io/terms/
    contact:
      email: frank@foo.com
    license:
      name: Apache 2.0
      url: http://www.apache.org/licenses/LICENSE-2.0.html
  servers:
  - url: /wyzx-pc 

值得注意的有:

  • resourcePackages 要扫描的包名,可以不断添加。
  • openAPI.servers 访问接口的前缀,也就是 Web 项目名称。这里配置正确了才能让 try it out 测试发送 HTTP 请求。

附,我的配置:

<servlet>
	<!-- 生成接口文档服务 --> 
	<servlet-name>OpenApi</servlet-name>
	<servlet-class>com.ajaxjs.cms.controller.ApiDocController</servlet-class>

	<init-param>
		<param-name>openApi.configuration.resourcePackages</param-name>
		<!-- 指定扫描的包 -->
		<param-value>com.ajaxjs.shop</param-value>
	</init-param>

	<!-- 另外可以在 classpath 中引入配置文件 openapi-configuration.json or openapi-configuration.yaml -->

	<!-- 还可以在下面配置中指明配置文件的位置 -->
	<init-param> <param-name>openApi.configuration.location</param-name> 
		<param-value>/openapi.yaml</param-value> </init-param>

	<load-on-startup>2</load-on-startup>
</servlet> 

<servlet-mapping>
	<servlet-name>OpenApi</servlet-name>
	<url-pattern>/admin/openapi/*</url-pattern>
</servlet-mapping> 


import io.swagger.v3.core.util.Json;
import io.swagger.v3.core.util.Yaml;
import io.swagger.v3.jaxrs2.integration.ServletOpenApiContextBuilder;
import io.swagger.v3.oas.integration.OpenApiConfigurationException;
import io.swagger.v3.oas.integration.OpenApiContextLocator;
import io.swagger.v3.oas.integration.api.OpenApiContext;
import io.swagger.v3.oas.models.OpenAPI;
import org.apache.commons.lang3.StringUtils;

import javax.servlet.ServletConfig;
import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;
import java.io.PrintWriter;

import static io.swagger.v3.jaxrs2.integration.ServletConfigContextUtils.getContextIdFromServletConfig;

public class ApiDocController extends HttpServlet {
	private static final long serialVersionUID = 5041371253005960693L;

	public static final String APPLICATION_JSON = "application/json";
	public static final String APPLICATION_YAML = "application/yaml";
	public static final String ACCEPT_HEADER = "Accept";

	@Override
	public void init(ServletConfig config) throws ServletException {
		super.init(config);
		String ctxId = getContextIdFromServletConfig(config);
		
		try {
			new ServletOpenApiContextBuilder<>().servletConfig(config).ctxId(ctxId).buildContext(true);
		} catch (OpenApiConfigurationException e) {
			e.printStackTrace();
		}
	}

	// TODO move to own servlet non jaxrs project and reference from there
	// TODO cleanup and errors
	@Override
	protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
		req.setCharacterEncoding("utf-8");
		resp.setCharacterEncoding("utf-8");

		String ctxId = getContextIdFromServletConfig(getServletConfig());
		OpenApiContext ctx = OpenApiContextLocator.getInstance().getOpenApiContext(ctxId);
		OpenAPI oas = ctx.read();

		String type = "json";

		String acceptHeader = req.getHeader(ACCEPT_HEADER);
		if (!StringUtils.isBlank(acceptHeader) && acceptHeader.toLowerCase().contains(APPLICATION_YAML)) {
			type = "yaml";
		} else {
			// check URL:
			if (req.getRequestURL().toString().toLowerCase().endsWith("yaml")) {
				type = "yaml";
			}
		}

		boolean pretty = false;
		if (ctx.getOpenApiConfiguration() != null && Boolean.TRUE.equals(ctx.getOpenApiConfiguration().isPrettyPrint())) {
			pretty = true;
		}

		resp.setStatus(200);

		try(PrintWriter pw = resp.getWriter();) {
			if (type.equalsIgnoreCase("yaml")) {
				resp.setContentType(APPLICATION_YAML);
				pw.write(pretty ? Yaml.pretty(oas) : Yaml.mapper().writeValueAsString(oas));
			} else {
				resp.setContentType(APPLICATION_JSON);
				pw.write(pretty ? Json.pretty(oas) : Json.mapper().writeValueAsString(oas));
			}
		}
	}
}
展开阅读全文

没有更多推荐了,返回首页