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.
Almost everything is ok instead three issues. At the first - this is my 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?
{
"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..
2) How can I remove "/api-docs/resources" from apis? I use only 'employee' class, not 'resources'.
3) If I type http://localhost:8080/rest/api-docs/employee
I have my methods and '/' main URL which is empty. Can I remove it?
I've tried a lot of configurations. Am I missed something?
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.
1) You don't want to get rid of api-docs in 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.
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.
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 .
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.
I've solved this in this way:
~/src/main/webapp/swagger-ui/api-docs.json
http://localhost:8080/swagger-ui/api-docs.json
to your discoveryUrl path in index.html
of you /swagger-ui
directory 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:
{
"apiVersion": "1.0",
"swaggerVersion": "1.1",
"basePath": "http://localhost:8080/rest",
"apis": [
{
"path": "/api-docs.json/employee",
"description": ""
}
]
}
and swagger-ui/index.html
settings
<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>
The technical post webpages of this site follow the CC BY-SA 4.0 protocol. If you need to reprint, please indicate the site URL or the original address.Any question please contact:yoyou2525@163.com.