4

在我的项目中，我使用 Maven、Jetty、Swagger、Java 和 Jersey 来创建 REST API。我还使用 Swagger 为我的 API 创建漂亮的文档。

几乎一切都很好，而不是三个问题。一开始 - 这是我的 web.xml

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://java.sun.com/xml/ns/javaee" xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
    xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
    version="2.5">
    <display-name>Restful Web Application</display-name>

    <context-param>
        <param-name>contextConfigLocation</param-name>
        <param-value>classpath:applicationContext.xml</param-value>
    </context-param>

    <listener>
        <listener-class>
            org.springframework.web.context.ContextLoaderListener
        </listener-class>
    </listener>

    <listener>
        <listener-class>
            org.springframework.web.context.request.RequestContextListener
        </listener-class>
    </listener>

    <servlet>
        <servlet-name>jersey-serlvet</servlet-name>
        <servlet-class>com.sun.jersey.spi.spring.container.servlet.SpringServlet</servlet-class>

        <init-param>
            <param-name>com.sun.jersey.config.property.packages</param-name>
            <param-value>com.pjdb.rest;com.wordnik.swagger.jaxrs;</param-value>
        </init-param>

        <init-param>
            <param-name>com.sun.jersey.api.json.POJOMappingFeature</param-name>
            <param-value>true</param-value>
        </init-param>

        <init-param>
            <param-name>api.version</param-name>
            <param-value>1.0</param-value>
        </init-param>

        <init-param>
            <param-name>swagger.api.basepath</param-name>
            <param-value>http://localhost:8080/rest</param-value>
        </init-param>

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

    <servlet>
        <servlet-name>Bootstrap</servlet-name>
        <servlet-class>com.pjdb.rest.Bootstrap</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>jersey-serlvet</servlet-name>
        <url-pattern>/rest/*</url-pattern>
    </servlet-mapping>

    <filter>
        <filter-name>ApiOriginFilter</filter-name>
        <filter-class>com.pjdb.rest.utils.ApiOriginFilter</filter-class>
    </filter>

    <filter-mapping>
        <filter-name>ApiOriginFilter</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>

</web-app>

1）如何从listingPath的开头删除api-docs？

{
  "apiVersion": "1.0",
  "swaggerVersion": "1.1",
  "basePath": "http://localhost:8080/rest",
  "apis": [
    {
      "path": "/api-docs/resources",
      "description": ""
    },
    {
      "path": "/api-docs/employee",
      "description": ""
    }
  ]
}

我想在路径的开头删除 /api-docs ..

2) 如何从 api 中删除“/api-docs/resources”？我只使用“员工”类，而不是“资源”。

3）如果我输入http://localhost:8080/rest/api-docs/employee我的方法和'/'主 URL 是空的。我可以删除它吗？

我尝试了很多配置。我错过了什么吗？

4

2 回答 2

2

我以这种方式解决了这个问题：

  1. 将 Swagger 生成的 api-docs.json 保存到硬盘
  2. 根据需要编辑生成的 JSON
  3. 将此文件复制到~/src/main/webapp/swagger-ui/api-docs.json
  4. 放入您目录http://localhost:8080/swagger-ui/api-docs.json中的 discoveryUrl 路径index.html/swagger-ui

此方法需要您，如果有任何变化，您必须自己修改主列表，但它是安全且有效的解决方案。

我的 api-docs.json 看起来像这样：

{
    "apiVersion": "1.0",
    "swaggerVersion": "1.1",
    "basePath": "http://localhost:8080/rest",
    "apis": [
        {
            "path": "/api-docs.json/employee",
            "description": ""
        }
    ]
}

和swagger-ui/index.html设置

<script type="text/javascript">
    $(function () {
        window.swaggerUi = new SwaggerUi({
            discoveryUrl:"http://localhost:8080/swagger-ui/api-docs.json",
            apiKey:"special-key",
            dom_id:"swagger-ui-container",
            supportHeaderParams: false,
            supportedSubmitMethods: ['get', 'post', 'put'],
            onComplete: function(swaggerApi, swaggerUi){
                if(console) {
                    console.log("Loaded SwaggerUI")
                    console.log(swaggerApi);
                    console.log(swaggerUi);
                }
              $('pre code').each(function(i, e) {hljs.highlightBlock(e)});
            },
            onFailure: function(data) {
                if(console) {
                    console.log("Unable to Load SwaggerUI");
                    console.log(data);
                }
            },
            docExpansion: "none"
        });

        window.swaggerUi.load();
    });

</script>
于 2013-01-10T19:10:47.363 回答
2

尽管我不是 Swagger 专家，但我将尝试回答您的所有三个问题。我还建议与 IRC 上的 Swagger 开发人员交谈——他们的响应速度非常快。我认为让 Swagger “自动”工作是值得的，这样您就不必手动更新它——这对我来说似乎不是最佳选择。

1) 您不想在列表路径中删除api-docs - 您想要列表的某种唯一名称。它不一定是api-docs - 例如，我使用资源- 但在 Swagger 上，您需要某种前缀来区分您的实际 REST 资源及其描述。所以我认为这根本不是问题。

2）您是否有一个扩展com.wordnik.swagger.jaxrs.JavaApiListing的类，可能称为ApiResourceListing。这就是您确定 Swagger 文档的入口点的地方。也许您有一个像这样指向/resources的额外类？（它也可能是import com.wordnik.swagger.jaxrs.listing.ApiListing的扩展，如果您没有在 REST 地址中使用格式后缀，则可以使用它。

3）我不知道这个。就像我一开始说的那样，也许可以在他们的 IRC 或他们的谷歌小组上询问 Swagger 的人。

4）这个答案与 Swagger 1.2 相关。如果您最近刚刚遇到这个问题，您可能想查看Swagger Jax-RS 教程，该教程已针对 1.3 版进行了更新。

于 2013-02-05T17:44:50.523 回答