Swagger UI 未在 index.html 页面上显示任何内容
Posted
技术标签:
【中文标题】Swagger UI 未在 index.html 页面上显示任何内容【英文标题】：Swagger UI Not Displaying Any Content On index.html Page 【发布时间】：2015-07-31 19:51:00 【问题描述】：已更新以下解决方案！！！ ///////////////////////////////////////// //////////// 感谢下面 Ron 的建议，我稍微修改了我的设置以使用 BeanConfig 而不是 SwaggerConfig 并使其正常工作。为了做到这一点，我必须修改 servlet，并且（我相信这是缺少的部分）将 BeanConfig 条目添加到 spring 应用程序上下文文件中，以便 spring 获取资源。我在显示旧代码和新代码/更新代码的代码中包含了以下带有 cmets 的更新。有可能我可以继续使用 SwaggerConfig（也许我只是在 spring 应用程序上下文文件中也缺少一些东西？）但是 BeanConfig 有效，所以我将保持原样。 ///////////////////////////////////////// ////////////
我正在尝试让 Swagger 与我的本地基于 REST 的 Java 应用程序一起运行，并且已经取得了相当大的进展。但是，当我试图让 Swagger UI 正常工作时，我似乎遗漏了一些简单的东西。
每当我实际点击这个地址时：http://localhost:9082/mbl/index.html 我会在顶部看到一个绿色的小招摇标题，但下面是一个空白的白色主体，下面没有任何内容。我不应该在页面正文中看到更多内容吗？
我的堆栈是这样的：Java 6 / Wink / Spring 3.1 / Jackson 2.5 / JAX-RS (JSR-311) 我正在使用以下 Swagger jar：swagger-annotations-1.3.10.jar / swagger-core_2 .10-1.3.10.jar / swagger-jaxrs_2.10-1.3.10.jar.
现在，当我点击http://localhost:9082/mbl/services/api-docs 时，我已经设法获得了一些看起来像这样的 json 显示：
"apiVersion":"1.0","swaggerVersion":"1.2","info":"title":"Java API","description":"The following documentation contains the REST Service API useful for interacting with web services.","termsOfServiceUrl":"terms of service","contact":"email@test.com","license":"license type","licenseUrl":"license url"
我可以看到这是从我的 SwaggerServlet.java 生成的，如下所示：
package com.somewhere.mblsvc.web;
import...
public class SwaggerServlet extends HttpServlet
private static final long serialVersionUID = 1L;
/* additional working code */
BeanConfig beanConfig;
public void setBeanConfig(BeanConfig beanConfig)
this.beanConfig = beanConfig;
/* end additional working code */
@Override
public void init(ServletConfig servletConfig)
try
/* code from original post*/
// SwaggerConfig swaggerConfig = new SwaggerConfig();
// ConfigFactory.setConfig(swaggerConfig);
// swaggerConfig.setBasePath("/mbl/services");
// swaggerConfig.setApiVersion("1.0");
// swaggerConfig.setApiInfo(new ApiInfo("Java API", "The following //documentation contains the REST Service API useful for interacting with web //services.", "terms of service", "email@test.com", "license type", "license //url"));
// ScannerFactory.setScanner(new DefaultJaxrsScanner());
// ClassReaders.setReader(new DefaultJaxrsApiReader());
/* end code from original post*/
/* updated working code */
beanConfig.setBasePath("/mbl/x-services");
beanConfig.setVersion("1.0");
beanConfig.setResourcePackage("com.somewhere.mblsvc.resources");
beanConfig.setScan(true);
/* end updated working code */
catch (Exception e)
e.printStackTrace();
另外，我的 spring 应用程序上下文 xml 文件中有以下内容：
<bean class="org.apache.wink.spring.Registrar">
<property name="classes">
<set value-type="java.lang.Class">
</set>
</property>
<property name="instances">
<set>
<ref local="jaxbProvider" />
<ref local="apiDeclarationProvider" />
<ref local="apiListingResourceJson" />
<ref local="resourceListingProvider" />
</set>
</property>
<!-- Jackson Providers -->
<bean id="jaxbProvider" class="com.fasterxml.jackson.jaxrs.json.JacksonJaxbJsonProvider" >
<property name="mapper" ref="jacksonObjectMapper"/>
</bean>
<bean id="jacksonObjectMapper" class="com.fasterxml.jackson.databind.ObjectMapper" >
<property name="annotationIntrospector" ref="jacksonAnnotationIntrospector" />
</bean>
<bean id="jacksonAnnotationIntrospector" class="com.fasterxml.jackson.databind.introspect.AnnotationIntrospectorPair" >
<constructor-arg ref="primaryAnnotationIntrospector" />
<constructor-arg ref="secondaryAnnotationIntrospector" />
</bean>
<bean id="primaryAnnotationIntrospector" class="com.fasterxml.jackson.module.jaxb.JaxbAnnotationIntrospector" />
<bean id="secondaryAnnotationIntrospector" class="com.fasterxml.jackson.databind.introspect.JacksonAnnotationIntrospector" />
<!-- Swagger Configuration and Providers -->
<!-- additional working code -->
<bean id="beanConfig" class="com.wordnik.swagger.jaxrs.config.BeanConfig">
<property name="title" value="Java API"/>
<property name="version" value="1.0" />
<property name="basePath" value="/mbl/services"/>
<property name="resourcePackage" value="com.somewhere.mblsvc.resources"/>
<property name="scan" value="true"/>
</bean>
<!-- end additional working code -->
<bean id="apiDeclarationProvider" class="com.wordnik.swagger.jaxrs.listing.ApiDeclarationProvider" />
<bean id="apiListingResourceJson" class="com.wordnik.swagger.jaxrs.listing.ApiListingResourceJSON" />
<bean id="resourceListingProvider" class="com.wordnik.swagger.jaxrs.listing.ResourceListingProvider" />
我的 web.xml 看起来像这样：
<!-- REST servlet that dispatches to the App (resource class). Remove Init params entry containing application file -->
<servlet>
<servlet-name>Wink Servlet</servlet-name>
<servlet-class>org.apache.wink.server.internal.servlet.RestServlet</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>Wink Servlet</servlet-name>
<url-pattern>/services/*</url-pattern>
</servlet-mapping>
<!-- Enabling Swagger servlet -->
<servlet>
<servlet-name>Swagger Servlet</servlet-name>
<servlet-class>com.somewhere.mblsvc.web.SwaggerServlet</servlet-class>
<load-on-startup>-1</load-on-startup>
</servlet>
<servlet-mapping>
<servlet-name>Swagger Servlet</servlet-name>
<url-pattern>/api-docs</url-pattern>
</servlet-mapping>
这是我的 Resource 类的 sn-p：
@Path("test")
@Api(value ="test", description="Test Services")
@Consumes( MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML )
@Produces( MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML )
public class TestResource
.
.
.
@GET
@Path("testInfo")
@ApiParam(defaultValue="you would put test case input here for a post")
@ApiOperation(value="Composite service returning extensive test information", response=com.somewhere.mblsvc.messages.test.testinfo.pojo.UserResponseMessage.class)
@ApiResponses(value=
@ApiResponse(code=200, message="OK"),
@ApiResponse(code=500, message="Internal Error")
)
@JsonSerialize(include=JsonSerialize.Inclusion.ALWAYS)
public Response getTestInfo(@Context HttpHeaders headers,
@CookieParam(value = "testBrand") String testBrand)
.
.
.
最后，我的 index.html 中唯一重要的部分（我可以说）如下所示：
<script type="text/javascript">
$(function ()
var url = window.location.search.match(/url=([^&]+)/);
if (url && url.length > 1)
url = url[1];
else
url = "http://" + window.location.hostname + (window.location.port ? ':'+ window.location.port: '') + "/mbl/services/api-docs";
.
.
.
我会很乐意根据需要提供更多信息。有谁知道我可能会错过什么？
非常感谢！
【问题讨论】：
【参考方案1】：核心问题是您的资源没有真正被扫描。您现在确实得到了基本的 Swagger 响应，但是如果您查看内容，其中没有 API 定义。
因此，swagger-ui 无法显示任何内容，因为没有什么可显示的。
虽然我很好奇您是如何获得上述配置的，但事实是集成可以更简单。我们没有 Wink 的特定文档（我们应该），但这个想法与任何 JAX-RS 集成都非常相似。
我推荐以下步骤：
-
迁移到 swagger-core 1.5。很明显，这是一个新的集成，没有理由不使用它。
查看wink sample - 应该真的很容易理解。
阅读 guides 了解 1.5 - 它们不是用于眨眼，但它们都相似，您可以推断为眨眼。
查看migration guide，因为它还包含可能对您有所帮助的详细信息。
我意识到这并不能完全解决当前的问题，但在这种情况下我宁愿推广正确的整体解决方案。
【讨论】：
感谢罗恩的回复。不幸的是，我没有选择迁移到 1.5 的选项……我的组织尚未批准该版本，而且其中的政治因素不在我的控制范围内。所以现在我需要用 1.3 来实现。我用资源类上的一些注释编辑了上面的问题，以尝试完成我的示例。你能帮忙解决手头的问题吗？至于我是如何做到这一点的......我基本上使用我的技术堆栈在网上搜索示例并在这里结束。我想我很接近了…… 没关系，您仍然可以使用 1.3，它有一个示例和指南。我建议通过 BeanConfig 路径而不是 SwaggerConfig。遵循这些，应该没问题。 嗯...您上面的“眨眼示例”链接给了我一个 404。：/ 抱歉，我们昨天刚搬了样品（有史以来第一次）。对于 1.3，您可以在此处找到示例 - github.com/swagger-api/swagger-core/tree/v1.3.12/samples/… 哈。无可挑剔的时机。谢谢。以上是关于Swagger UI 未在 index.html 页面上显示任何内容的主要内容，如果未能解决你的问题，请参考以下文章
Swagger UI 未在 azure .net 核心中生成，但在本地工作
drf-yasg：图像字段未在 swagger ui 中显示