REST API - Swagger + Java + Jersey 错误的列表路径和其他 api
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/14262660/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
REST API - Swagger + Java + Jersey wrong listing path and additional apis
提问by mrzepinski
In my project I am using Maven, Jetty, Swagger, Java and Jersey for creating REST API. I also use Swagger to create nice-looking documentation for my API.
在我的项目中，我使用 Maven、Jetty、Swagger、Java 和 Jersey 来创建 REST API。我还使用 Swagger 为我的 API 创建漂亮的文档。
Almost everything is ok instead three issues. At the first - this is my web.xml
几乎一切都好，而不是三个问题。首先 - 这是我的 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) How to remove api-docs from the beginnig of listingPath?
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": ""
}
]
}
And I want to remove /api-docs at the beginning of the path..
我想删除路径开头的 /api-docs ..
2) How can I remove "/api-docs/resources" from apis? I use only 'employee' class, not 'resources'.
2) 如何从 apis 中删除“/api-docs/resources”？我只使用“员工”类，而不是“资源”。
3) If I type http://localhost:8080/rest/api-docs/employeeI have my methods
and '/' main URL which is empty. Can I remove it?
3) 如果我输入，http://localhost:8080/rest/api-docs/employee我有我的方法和空的“/”主 URL。我可以删除它吗？
I've tried a lot of configurations. Am I missed something?
我尝试了很多配置。我错过了什么吗？
采纳答案by mrzepinski
I've solved this in this way:
我以这种方式解决了这个问题：
- Save api-docs.json generated by Swagger to hard-drive
- Edit generated JSON as you need
- Copy this file to
~/src/main/webapp/swagger-ui/api-docs.json - Put
http://localhost:8080/swagger-ui/api-docs.jsonto your discoveryUrl path inindex.htmlof you/swagger-uidirectory
- 将 Swagger 生成的 api-docs.json 保存到硬盘
- 根据需要编辑生成的 JSON
- 将此文件复制到
~/src/main/webapp/swagger-ui/api-docs.json - 放入您的目录中的
http://localhost:8080/swagger-ui/api-docs.jsondiscoveryUrl 路径index.html/swagger-ui
This method needs from you, that you have to modify by yourself you main listing if anything change but it's safe and working solution.
这种方法需要您，如果有任何变化，您必须自己修改主要列表，但它是安全且有效的解决方案。
My api-docs.json looks like this:
我的 api-docs.json 看起来像这样：
{
"apiVersion": "1.0",
"swaggerVersion": "1.1",
"basePath": "http://localhost:8080/rest",
"apis": [
{
"path": "/api-docs.json/employee",
"description": ""
}
]
}
and swagger-ui/index.htmlsettings
和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>
回答by Eyal
I'll try to answer all three of your questions, although I'm hardly a Swagger expert. I'd also suggest talking to the Swagger devs on IRC, too- they're very quick to respond. I think it's worth getting Swagger to work "automatically" so that you don't have to manually update it- that seems less than optimal to me.
我将尝试回答您的所有三个问题，尽管我不是 Swagger 专家。我还建议与 IRC 上的 Swagger 开发人员交谈，他们也会很快做出回应。我认为让 Swagger“自动”工作是值得的，这样你就不必手动更新它——这对我来说似乎不太理想。
1) You don't want to get rid of api-docsin your listing path- you want some sort of unique name for your listings. It doesn't have to be api-docs- for example, I use resources- but you'll need some sort of prefix to differentiate between your actual REST resources and their descriptions, on Swagger. So I don't think this is a problem at all.
1) 您不想在您的列表路径中删除api-docs -您想要为您的列表使用某种独特的名称。它不一定是api-docs- 例如，我使用资源- 但您需要某种前缀来区分 Swagger 上的实际 REST 资源及其描述。所以我认为这根本不是问题。
2) Did you have a class that extends com.wordnik.swagger.jaxrs.JavaApiListing, perhaps called ApiResourceListing. That's where you determine the entry point to the Swagger docs. Maybe you had an extra class like this one which was pointing to /resources? (It might also be an extension of import com.wordnik.swagger.jaxrs.listing.ApiListing, which is what you use if you're not using a format suffix in your REST addresses.
2）您是否有一个扩展com.wordnik.swagger.jaxrs.JavaApiListing的类，可能称为ApiResourceListing。这就是您确定 Swagger 文档的入口点的地方。也许你有一个像这样指向/resources的额外类？（它也可能是import com.wordnik.swagger.jaxrs.listing.ApiListing的扩展，如果您没有在 REST 地址中使用格式后缀，则可以使用它。
3) I don't know about this one. Like I said in the beginning, maybe ask the Swagger guys on their IRC or their google group.
3）我不知道这个。就像我一开始说的那样，也许可以在他们的 IRC 或他们的google group上询问 Swagger 的人。
4) This answer is relevant for Swagger 1.2. If you've just encountered this question recently, you might want to check out the Swagger Jax-RS tutorial, which has been updated for version 1.3.
4）这个答案与 Swagger 1.2 相关。如果您最近刚刚遇到这个问题，您可能需要查看Swagger Jax-RS 教程，该教程已针对 1.3 版进行了更新。
