Problem converting from 1.2.5 to 1.3.0-RC1 using Java and JaxRS Missing all the docs to my paths

[Scott Ryan]

I am converting from 1.2.5 to 1.3.0 and seeing some minor issues.  I am using JaxRS with Jersey and all was working with 1.2.5 except some of the sub resource support that I need so i migrated to 1.3.0.  I read the migration guide and release note and made the proper code
changes however there are some changes I had to make to compile and run:

I initially had to have a servlet to remove the .json ending from my paths but it looks like the method I was using JaxrsApiReader.setFormatString(""); was removed in 1.3.0 so I assumed I no longer needed the code and removed it.  
I also had to have my own ApiListingResourceJSON in order to handle my paths.  The class I was extending ApiListing is no longer available so I removed my class and put the swagger class in my Jersey configuration

Now when I bring up the URL   api/api-docs  I only get the following:

{

• "apiVersion": "0.0",
• "swaggerVersion": "1.2"

}

Non of my resources are documented.  Is there some other change i am missing or did I remove some things I did not need to remove? 


Scott Ryan

[tony tam]

Hi Scott, you're missing one other thing, see here:

https://github.com/wordnik/swagger-core/blob/1.3-RC3/samples/java-jaxrs/src/main/webapp/WEB-INF/web.xml#L29-L45

  <servlet>
    <servlet-name>DefaultJaxrsConfig</servlet-name>
    <servlet-class>com.wordnik.swagger.jaxrs.config.DefaultJaxrsConfig</servlet-class>
    <init-param>
      <param-name>api.version</param-name>
      <param-value>1.0.0</param-value>
    </init-param>
    <init-param>
      <param-name>swagger.api.basepath</param-name>
      <param-value>http://localhost:8002/api</param-value>
    </init-param>
    <load-on-startup>2</load-on-startup>
  </servlet>

[tony tam]

Also Scott, I'm working on a migration guide for the specific implementations, which would cover this point.  Coming soon...

[Scott Ryan]

That did the trick so now I am getting the proper results.  I removed the basepath and filter parameters and it worked like a champ.  Now I am trying to figure out how to get the sub resources to document.  I am on version 1.3.0-RC1 and don't see any of the docs in for the sub resource.  I have defined the sub resource as follows:

 @Path("/inspections/fields/{id}")
    public def inspectionField(@PathParam("id") String fieldId) {
        return new FieldItemResource(fieldId)
    }

So I need any annotations on the part above or anything on the sub resource.  I don't have any annotations on the sub resource class other than operations.  Are there any samples I could look at in github

Scott Ryan

[tony tam]

Hi Scott, there is a subresource example here:

https://github.com/wordnik/swagger-core/tree/1.3-RC3/samples/java-jaxrs-subresource

I believe the subresource needs to have @Api annotations as well.

On another note, are you still using grails?  I was just looking at updating the example in github and have trouble a sample app picking up our JAXRS resource, like such:

https://github.com/wordnik/swagger-core/blob/1.3-RC3/samples/java-grails2/src/groovy/com/wordnik/swagger/sample/resource/ApiListing.groovy

Any tips on that? :)

[Scott Ryan]

We are still using grails but have gone to a move native approach and not using the plugin so that we could use native libraries at the versions we choose. It works well putting the resources either in the grails directory or the source directory and I was able to get the latest version to work.  I will have a look at your example code this evening and see if i can get it working.  This is exactly the same implementation we had prior to moving to 1.3.0.  We Don't use the ApiListing any longer.  We removed it and the new code found all of our resources.    I can push up a simple example if you like

Scott Ryan

Scott Ryan
President/CTO
Soaring Eagle L.L.C.
Highlands Ranch, Co. 80130
(303) 263-3044
sc...@theryansplace.com
www.soaringeagleco.com

--
You received this message because you are subscribed to a topic in the Google Groups "Swagger" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/swagger-swaggersocket/77q-XSey95k/unsubscribe.
To unsubscribe from this group and all its topics, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[tony tam]

Hi Scott, if you have a chance to peek at that sample, I'd really appreciate it.  I too would prefer to let the app pick up the swagger resources without adding additional classes.

Tony

To unsubscribe from this group and all its topics, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

[Scott Ryan]

I was looking more for the support of Sub Resource Locators which by definition do not contain an HTTP Verb.  We have many of our services constructed this way and it helps a lot for reuse versus the normal sub resource pattern.   We have not been able to get Swagger to delve down into the sub resource without the http verb.  I will try to see if I can fool it in some way but we would prefer to have native support.   Here is a quick example

@Path("/item")

public class ItemResource {

    @Context UriInfo uriInfo;

 

    @Path("content")

    public ItemContentResource getItemContentResource() {

        return new ItemContentResource();

    }

 

    @GET

    @Produces("application/xml")

        public Item get() { ... }

    }

}

 

public class ItemContentResource {

 

    @GET

    public Response get() { ... }

 

    @PUT

    @Path("{version}")

    public void put(@PathParam("version") int version,

                    @Context HttpHeaders headers,

                    byte[] in) {

        ...

    }

}



Scott Ryan
President/CTO
Soaring Eagle L.L.C.
Highlands Ranch, Co. 80130
(303) 263-3044
sc...@theryansplace.com
www.soaringeagleco.com

On Tue, Jul 30, 2013 at 8:03 AM, tony tam <feh...@gmail.com> wrote:

--

You received this message because you are subscribed to a topic in the Google Groups "Swagger" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/swagger-swaggersocket/77q-XSey95k/unsubscribe.

To unsubscribe from this group and all its topics, send an email to swagger-swaggers...@googlegroups.com.

[tony tam]

It seems to me that this is doable, but there's a bug/bad implementation in the swagger subresource logic.  It looks to be appending the @Api(value={...}) to the subresource instead of just using the @Path annotations.

But you will need to add an @Api() annotation on your subresource for this to be picked up.

// parent resource

@Path("/pet")

@Api(value = "/pet", description = "Operations about pets")

@Produces(Array(MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML, MediaType.TEXT_PLAIN, MediaType.TEXT_HTML))

class PetResource extends RestResourceUtil {

  @Path("/sub")

  def subResource(): SubResource = {

    new SubResource()

  }

}

// the subresource

@Api(value = "", description = "Subresource methods")  // <= this needs to be fixed

@Produces(Array("application/json"))

class SubResource extends RestResourceUtil {

  @GET

  @ApiOperation(value = "Get user by user name", response = classOf[User])

  @ApiResponses(Array(

    new ApiResponse(code = 400, message = "Invalid username supplied"),

    new ApiResponse(code = 404, message = "User not found")))

  def getUserByName(

    @ApiParam(value = "The name that needs to be fetched. Use user1 for testing. ", required = true)@QueryParam("username") username: String) = {

  // ...

}

To unsubscribe from this group and all its topics, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

[Scott Ryan]

That did not seem to be the fix. I will build up an example app this weekend and send it to you for an example to be used anytime.   I will try other ideas but hopefully the example will shed some light on the issue.  It should also be a working grails example to help debug the other issues.  Let me know a good place to upload the example once i have it ready

Scott Ryan

[tony tam]

you can just email it to me, fehguy at gmail

[Scott Ryan]

I did send a zip and I also posted the test project on github at

https://github.com/scryan7371/swagtest

Scott Ryan

[tony tam]

Hi Scott, thanks.  Just FYI, I did update the grail2 quickstart here:

https://github.com/wordnik/swagger-core/wiki/Java-grails2-Quickstart

If you see anything else missing, please feel free to add it in there.  I will add a subresource section shortly and look into your specific issue.

[Scott Ryan]

Any progress on this one?  I am still missing references to my sub resources.

Thanks