REST API - Swagger + Java + Jersey错误的列表路径和额外的apis

时间:2013-01-10 16:31:14

标签: java rest jersey jetty swagger

在我的项目中,我使用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的beginnig中删除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是空的。我可以删除吗?

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

2 个答案:

答案 0 :(得分:2)

我会尝试回答你所有的三个问题,尽管我不是一个Swagger专家。我也建议在IRC上与Swagger开发人员交谈 - 他们很快就会做出回应。我认为让Swagger“自动”工作是值得的,这样你就不必手动更新它 - 这对我来说似乎不太理想。

1)您不希望在列表路径中删除 api-docs - 您希望列表具有某种唯一名称。它不一定是 api-docs - 例如,我使用资源 - 但你需要某种前缀来区分你的实际REST资源和它们的关于Swagger的描述。所以我认为这根本不是问题。

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

3)我不知道这个。就像我在开始时所说的那样,或许可以向他们的IRC或他们的google group询问Swagger的人。

4)这个答案与Swagger 1.2相关。如果您最近刚遇到此问题,可能需要查看已针对1.3版更新的Swagger Jax-RS tutorial

答案 1 :(得分:1)

我已经用这种方式解决了这个问题:

  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放入您index.html目录的/swagger-ui中的discoveryUrl路径
  5. 此方法需要您,您必须自己修改主列表 如果有什么变化,但它是安全和有效的解决方案。

    我的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>