martypitt/swagger-springmvc-example

Sample project for SpringMVC Swagger intergration

IMPORTANT! This project is no longer being maintained. Please look at the more recently updated demo repository that supports 0.8.x and beyond

Before you begin

swagger-springmvc must be installed in your local maven repository.

Build and Run

mvn jetty:run

Go to http://localhost:8080/swagger-springmvc-test/index.html

The textfield should be filled with http://localhost:8080/swagger-springmvc-test/api-docs

swagger-springmvc-example's Issues

Adding the dependency breaks existing request mappings

My project uses a hybrid of both XML and annotation based configuration (heavy on the XML).

Simply adding a dependency to the ivy configuration file breaks my application. It starts up error free, but none of the mappings work anymore.

There is likely some initializing bean of some sort that plays around with mappings, but I haven't figured out where it comes from.

As well, where do questions/feature requests get posted? As a new issue?

Thanks.

Could not build the example project due to dependency issue

Error building in "mvn package install" command because of the repository not being available.

[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 1:39.205s
[INFO] Finished at: Sat May 24 15:00:06 IST 2014
[INFO] Final Memory: 7M/234M
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal on project swagger-springmvc-test: Could not resolve dependencies for project com.mangofactory.swagger:swagger-springmvc-test:war:0.5.0-SNAPSHOT: Cou
ld not find artifact com.mangofactory:swagger-springmvc:jar:0.7.0-SNAPSHOT in sonatype (https://oss.sonatype.org/) -> [Help 1]
[ERROR]
[ERROR] To see the full stack trace of the errors, re-run Maven with the -e switch.
[ERROR] Re-run Maven using the -X switch to enable full debug logging.
[ERROR]
[ERROR] For more information about the errors and possible solutions, please read the following articles:
[ERROR] [Help 1] http://cwiki.apache.org/confluence/display/MAVEN/DependencyResolutionException

Installation issue - dependencies

Hi there,
I'm a bit new to Spring and Maven so please bear with me.

I've installed swagger-springmvc by cloning it and running 'mvn install'. That seemed to go fine, and it installed into my local Maven repo.

I then cloned swagger-springmvc-example and tried to install 'mvn install', but I got this:

[ERROR] Failed to execute goal on project swagger-springmvc-test: Could not resolve dependencies for project com.mangofactory.swagger:swagger-springmvc-test:war:0.0.1-SNAPSHOT: Failure to find com.mangofactory:swagger-springmvc:jar:0.1.6-SNAPSHOT in http://mynexus:8301/nexus/content/groups/public was cached in the local repository, resolution will not be reattempted until the update interval of Public has elapsed or updates are forced -> [Help 1]

(I've changed the address of my nexus server for privacy reasons to 'mynexus' in the transcript).

Swagger-springmvc got installed to .m2/repository/com/mangofactory/swagger-springmvc/0.2.3-SNAPSHOT/swagger-springmvc-0.2.3-SNAPSHOT.jar - so I'm thinking that the versions are out of sync.

Do you have any idea how I could solve this?

Thanks,

capncodewash

Need help

Hi Marty, I wonder if you can help me. I feel I'm getting close but I've yet to produce an api-docs folder. Firstly, am I correct in understanding my target folder should contain an api-docs folder somewhere and it gets read by the swagger-ui?

So... I'm using swagger-springmvc-0.8.3 from Maven Central (which brought in swagger-core_2.10-1.3.2). I've cloned swagger-springmvc-example at version 0.5.0-SNAPSHOT but it depends on swagger-springmvc-0.7.0 which I can't find. Do you have plans to modernize the example to use 0.8.3? It looks to me that some important API has been removed from 0.8.3, is that correct? Will it still somehow support @apimodel and @ApiErrors? Would I be better off using 0.6.6?

I've tried hacking the example to work with 0.8.3 but ended up commenting out so much that it doesn't work. I'm wondering though if my project which I've converted to use swagger-springmvc-0.8.3 can be fixed.

I've added the properties file and the spring-context.xml entries that you have minus the DocumentationConfig and ExtensibleModule - are they required? I see nothing about swagger in the output of "mvn clean install -e" but lots in "mvn clean install -X" output, though only about copying swagger.properties to classes folder. Is there anything in particular I should be looking for?

If you'd prefer to communicate by email, my address is [email protected]. Thanks for the work and the sharing!

Craig

Issue on RequestMapping with value like "/api/sample"

Swagger SpringMVC integration works fine with path @RequestMapping(value = "/sample"), but not with @RequestMapping(value = "/api/sample")

Could you fix it or give me some hints in order to fix it ?

Swagger UI is not working

I am trying to run Swagger UI(url http://localhost:8080/swagger-springmvc-test/usage/index.html) on branch "rel-0.6-java-config" and getting JS error:
Uncaught TypeError: Cannot call method 'toLowerCase' of undefined swagger.js:381

can Use swagger-springMVC with maven ?

can you help me build app example use swagger-springMVC with maven (without scala)?

Can't compile project

All the Swagger annotations in controllers are from com.wordnik.swagger.core package.
But it seems that these annotations moved to com.wordnik.swagger.annotations package.
At least project started to compile after this change.

Error generate XML of

@dilipkrish When I tries see the XML of my service happens an error(the page can't be rendered). I could see that occurrs error because my model have a field that is generic list, when I removed the list, my application returned works and I could see the XML.

Error message:

This page contains the following errors:

error on line 1 at column 10260: Extra content at the end of the document
Below is a rendering of the page up to the first error.

Model
Customer{
String id;
String name;
List

address; ( with generic list occurs error, without generic list don't occurs error)

get and set...
}

Are you know any about this?

example update with swagger-springmvc:0.4.0-SNAPSHOT

please example (or create a branch) with update for swagger-springmvc:0.4.0-SNAPSHOT...

Thanks!

UI. No sorting example.

Hi! Could you please add sorting example? It's not clear how to sort operations.
I have configuration like this:

<bean id="swaggerConfiguration" class="com.mangofactory.swagger.SwaggerConfiguration">
    <property name="apiVersion" value="1.0"/>
    <property name="basePath" value="/rest/"/>
    <property name="extensions">
        <bean class="com.mangofactory.swagger.SwaggerConfigurationExtension">
            <property name="ignorableParameterTypes">
                <list>
                    <value type="java.lang.Class">
                        org.springframework.http.ResponseEntity
                    </value>
                </list>
            </property>
            <property name="operationComparator" ref="operationComparator"/>
            <property name="endPointComparator" ref="endPointComparator"/>
        </bean>
    </property>
</bean>

In this Configuration Documentation apis i.e. RequestMappings are sorted on ui, but operations are unsorted.

when i debug method applySorting i see that
DocumentationEndPoint operations list is empty and so it hasn't any sorting effect.

Can anybody help me?

Project doesn't work as expected

404 HTTP status for http://localhost:8080/swagger-springmvc-test/apidoc

According to DocumentationController main API info here: http://localhost:8080/swagger-springmvc-test/resources

and pets API info: http://localhost:8080/swagger-springmvc-test/resources/pets
and users API info: http://localhost:8080/swagger-springmvc-test/resources/users

index.html - does handle these urls correctly.
It waits for description on URLS:
http://localhost:8080/swagger-springmvc-test/pets
http://localhost:8080/swagger-springmvc-test/users

Maybe its a bug of swagger-springmvc module.

I would like don't display some fields

My new problem is: I would like don't display some fields in the object, example:
My Json request is this:
{
"id": "long",
"oneClick": "boolean",
"ddd": "string",
"email": "string",
"name": "string",
"telephone": "string",
"password": "string"
}

but I would want it is this:

{
"oneClick": "boolean",
"ddd": "string",
"email": "string",
"name": "string",
"telephone": "string",
"password": "string"
}

I call a POST action and id field is populated by my application.
Can you help me?

Which version of 'https://github.com/wordnik/swagger-ui' project, this example uses?

Also please mention when can we expect this example be built on latest ' 'https://github.com/wordnik/swagger-ui' project code

Use array/list in the request payload

Hi,

I don't know if it is possible, so I can do the same in the response payload.. my question is in relation of a request payload that has a list/array.

Example:

@RequestMapping(value = "/myuri", method = RequestMethod.POST)
public void category(Collection category)

The input in swagger should be:

[{
"categoryId": 123,
"categoryName": "My Category"
}]

But what ocurrs in swagger is:

{
"empty": "boolean"
}

Can you help me?

Need quick help on implementation/customization

I am seeing all the request URI's of my application twice in spring-mvc example app, any idea why is that?
Also I wanted to know where do we need to customize to see only the request URIs I am interested in.
And also observed some input classes were listed with only the class name but not the fields of it.

defult @ApiParam name not set.

hi.

I love swagger :)

I use swagger 0.2.4.
Today upgrade version 0.3.0.
Very Good.

but

        @ApiParam(value="useCache=true")
        @RequestParam(value="useCache",required=false) boolean useCache,

name is null

parameters: [
{
name: null,
defaultValue: "",
description: "useCache=true",
dataType: "boolean",
required: false,
allowableValues: null,
notes: "",
valueTypeInternal: null,
wrapperName: null,
internalDescription: null,
paramAccess: null,
allowMultiple: false,
paramType: "query"
},

0.2.4
name: useCache

please help me

stackoverflowerror for selfreferencing model object

hello
I have a model object which i return from a response of a resource using @responsebody annotation.
So the example project you can assume that Pet model object will have a reference to a List pets;
When i invoke api-doc,i get stackoverflow error.
I tried with example-project and it results in the same problem.

Thanks

json representation doesnt work

Hi,
Iam trying to get this example working for json
Here are the URLs.XML works fine but json is broken
It seems like
return apiReader.getDocumentation(fullUrl.substring(indexOfApiName));
returns api name with .json to the end and framework fails to recognise the resource
Here are the URLs iam trying to use

Json doesnt work but XML works
http://localhost:8080/swagger-springmvc-test/api-docs/pets.json
http://localhost:8080/swagger-springmvc-test/api-docs/pets

Both Of them works:
http://localhost:8080/swagger-springmvc-test/api-docs
http://localhost:8080/swagger-springmvc-test/api-docs.json

Spring No XML Example

Not entirely sure if this belongs here or on the actual swagger-springmvc project; tried to follow the given steps to get Swagger working with SpringMVC in a no XML environment: servlet 3, @configuration everywhere. Ended up doing the following:

1. Add a PropertyPlaceholderConfigurer to the existing Spring configuration class:

@Bean
public static PropertyPlaceholderConfigurer swaggerProperties() {
    final PropertyPlaceholderConfigurer swaggerProperties = new PropertyPlaceholderConfigurer();
    swaggerProperties.setLocation(new ClassPathResource("swagger.properties"));
    return swaggerProperties;
}

1. Modify the WebApplicationInitializer to load the DocumentationConfig:

// Create the 'root' Spring application context
AnnotationConfigWebApplicationContext ctx = new AnnotationConfigWebApplicationContext();
ctx.register(SpringBaseConfiguration.class, SpringWebConfiguration.class, DocumentationConfig.class);

I didn't have to create any other beans or instantiate any other objects.