Confusing Documentation

[ericsodt]

The documentation and demo's are very confusing and hard to build/deploy. Are there any simple example projects out there for people to get started?

If possible, instead of abstracting everything away with Springboot, can we see some examples using a simple Spring-MVC project (ie Hello World)

[dilipkrish]

What documentation are you referring to and what specifically is confusing? May be an opportunity to improve the documentation if you provide something concrete.

[dilipkrish]

This subproject is a vanilla spring mvc application example

[ericsodt]

Our concern with using that project is we do not have access to Gradle where we work, so we cannot deploy it. Do you have a build agnostic project example?

In most cases we end up creating eclipse dynamic web projects or Maven projects if there's a lot of dependencies, but unfortunately Gradle is not an option for us.

On Tue, Jul 7, 2015 at 3:34 PM, Dilip Krishnan notifications@github.com wrote:

This subproject https://github.com/springfox/springfox-demos/tree/master/spring-java-swagger is a vanilla spring mvc application example

— Reply to this email directly or view it on GitHub https://github.com/springfox/springfox-demos/issues/6#issuecomment-119311910 .

[dilipkrish]

the thing about gradle is that it is bootstrapped already using the gradle wrapper (gradlew). if you use the gradlew command it will automatically download everything you need.

./gradlew clean build #equivalent to mvn clean install

Its very simple to translate a gradle project to maven. Also we provide the instructions in our documentation have everything you need as regards maven or gradle.

Another great source to generate a skeleton project for maven is available at http://editor.swagger.io Generate Server -> Spring MVC, tho' the skeleton is a little out of date.

It would be much appreciated if you contribute a maven example that we can include in the spring demos, but we simply don't have the bandwidth to do that an maintain it unfortunately!

[ericsodt]

Thank for your response. I have tried creating a skeleton project with the swagger editor project, unfortunately, there's a bug that prevents its creation.

Also, I wouldn't expect mvn clean install to startup and deploy to a web container. Do you have anything setup to run mvn jetty:run?

[ericsodt]

I wanted to document my continued troubles using the springfox-demo project.

I pulled down the latest code and opened it into eclipse. I then opened a terminal and issued the following commands:

C:\eclipse\workspace\springfox-demos>gradle spring-java-swagger:appRun
:spring-java-swagger:compileJava UP-TO-DATE
:spring-java-swagger:processResources UP-TO-DATE
:spring-java-swagger:classes UP-TO-DATE
:spring-java-swagger:prepareInplaceWebAppClasses UP-TO-DATE
:spring-java-swagger:prepareInplaceWebAppFolder UP-TO-DATE
:spring-java-swagger:prepareInplaceWebApp UP-TO-DATE
:spring-java-swagger:appRun
19:25:42 INFO  Spring WebApplicationInitializers detected on classpath:     [springfoxdemo.java.swagger.ApplicationInitializer@60dce7ea]
19:25:42 INFO  Initializing Spring FrameworkServlet 'dispatcher'
....
Jul 07, 2015 7:25:47 PM org.springframework.web.servlet.handler.SimpleUrlHandlerMapping registerHandler
INFO: Mapped URL path [/swagger-ui.html] onto handler of type [class org.springframework.web.servlet.resource.ResourceHttpRequestHandler]
Jul 07, 2015 7:25:47 PM org.springframework.web.servlet.handler.SimpleUrlHandlerMapping registerHandler
INFO: Mapped URL path [/webjars/**] onto handler of type [class org.springframework.web.servlet.resource.ResourceHttpRequestHandler]
Jul 07, 2015 7:25:48 PM org.springframework.web.servlet.DispatcherServlet initServletBean
INFO: FrameworkServlet 'dispatcher': initialization completed in 5865 ms
19:25:48 INFO  Jetty 9.2.9.v20150224 started and listening on port 8080
19:25:48 INFO  spring-java-swagger runs at:
19:25:48 INFO    http://localhost:8080/spring-java-swagger
Press any key to stop the server.

However, when I visit the webpage I get a 404 error

HTTP ERROR 404
Problem accessing /spring-java-swagger/. Reason:
Not Found
Powered by Jetty://

[dilipkrish]

Have you read the readme?

[ericsodt]

@dilipkrish - If anything, I think that proves the point I was trying to make. Why do we need to run that script instead of just using native Gradle?

Also, yes; I did read the file and I am still getting the same response:

C:\eclipse\workspace\springfox-demos>gradlew spring-java-swagger:appRun
:spring-java-swagger:compileJava
warning: [options] bootstrap class path not set in conjunction with -source 1.7
1 warning
:spring-java-swagger:processResources
:spring-java-swagger:classes
:spring-java-swagger:prepareInplaceWebAppClasses
:spring-java-swagger:prepareInplaceWebAppFolder
:spring-java-swagger:prepareInplaceWebApp
:spring-java-swagger:appRun
20:13:49 INFO  Spring WebApplicationInitializers detected on classpath:     [springfoxdemo.java.swagger.ApplicationInitializer@60dce7ea]
20:13:50 INFO  Initializing Spring FrameworkServlet 'dispatcher'
Jul 07, 2015 8:13:50 PM org.springframework.web.servlet.DispatcherServlet initServletBean
INFO: FrameworkServlet 'dispatcher': initialization started
....
Press any key to stop the server.
Jul 07, 2015 8:14:03 PM org.springframework.web.servlet.PageNotFound noHandlerFound
WARNING: No mapping found for HTTP request with URI [/spring-java-swagger/] in     DispatcherServlet with name 'dispatcher'
Jul 07, 2015 8:14:06 PM org.springframework.web.servlet.PageNotFound noHandlerFound
WARNING: No mapping found for HTTP request with URI [/spring-java-swagger/] in     DispatcherServlet with name 'dispatcher'

HTTP ERROR 404 Problem accessing /spring-java-swagger/. Reason: Not Found Powered by Jetty://

[ericsodt]

I also wanted to document more confusion we are facing in regards to trying to figure out dependencies. To simplify the project, I would think adding the controllers into the project would make the most sense instead of using the ones in the dependent jar files.

Another source of confusion are the resourceHandler's: For example why do we need the following (classpath:/META-INF/resources/):

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {            

    registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
    registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");
}

A simpler project for people to get used to springfox might be very beneficial.

[dilipkrish]

To answer your questions:

If anything, I think that proves the point I was trying to make. Why do we need to run that script instead of just using native Gradle

Without repeating the official gradle documentation, the gradle wrapper is only so that you don't need to install gradle on the machine. Secondly, its a way to provide a specific version of gradle (2.4-rc-1) and not depend on the natively installed gradle, and that applies to CI environments as well.

Also, yes; I did read the file and I am still getting the same response:

If you had read the readme, you'd have known that

• the apidocs are @ http://localhost:8080/spring-java-swagger/v2/api-docs
• the swagger ui is available @ http://localhost:8080/spring-java-swagger/swagger-ui.html

If you were expecting that by going to http://localhost:8080/spring-java-swagger/ the browser would magically redirect you to one of those places, thats obviously not going to work, unless YOU write code for it.

To simplify the project, I would think adding the controllers into the project would make the most sense instead of using the ones in the dependent jar files.

Not sure what you mean.

For example why do we need the following (classpath:/META-INF/resources/)

This is for the convenience of library users and is completely optional. This is only needed if you want to use a pre-packaged version of the swagger-ui with your application. We've bundled a custom version of swagger-ui into a web jar and the we need to register resource handlers to serve the bundled swagger-ui.html. You'd have to do the same thing if you hand rolled your own solution. More info on web jars here.

A simpler project for people to get used to springfox might be very beneficial.

What constitutes "simple" is always a slippery slope. In our opinion, this is the simplest setup to have spring-swagger integration, which also includes the swagger-ui built in. Which is what 90% of the people want to accomplish. If you want instructions on a simpler setup the getting started documentation is the best place to go. In general the demo apps are targeted towards typical setups.

Lastly; and this is by no means tongue in cheek; this is all open source, and we love for you to give back to the community by either adding to the list of demos a sample maven setup or improving the documentation or contributing bug-fixes or even just plain sharing your ideas. Stuff that might be useful for folks similar to yourself. More importantly it would give us an idea as what you mean by "simpler project".

Hope that helped you with your confusion. I'd be happy address any more of your feedback or questions but non-constructive criticism is neither going to be productive for your nor this project.

[ericsodt]

@dilipkrish, thank you for such a thorough response. I will have to do some research on the links provided. I appreciate the time you took responding.

Thanks again