Swagger Core Scanning Web App But Not Generating Documentation

[David Rickard]

UCLA Library IT is making a stab at integrating Swagger into our webservices.

Our test app has two services, one which consumes JSON via PUT, one which generates JSON via GET.

We've Swagger Core into our application, following the instructions setup instructions here.

Our code is in GitHub: https://github.com/UCLALibrary/StatsServices

According to log4j output, our application is being scanned at startup:

2017-05-31 10:39:19 DEBUG ApiListingResource:47 - using scanner io.swagger.jaxrs.config.BeanConfig@78a92042
2017-05-31 10:39:19 DEBUG Reflections:185 - going to scan these urls:
file:/usr/local/pss/webapps/pss/WEB-INF/classes/
2017-05-31 10:39:19 INFO  Reflections:228 - Reflections took 12 ms to scan 1 urls, producing 10 keys and 26 values

However, the only output we get from https://our.app.edu/app/swagger.json is:

{
swagger: "2.0",
info:
{
version: "1.0.0"},
host: "webservices-test.library.ucla.edu",
basePath: "/pss",
schemes:
[
"https"]}

That is, the values defined in the SwaggerBootstrap servlet.

Is there a configuration step we're missing, or servlet config param we need to add to get the full Swagger output?

[Ron Ratovsky]

Hi David,

 

Yup, it looks like you skipped a step.

You mentioned the Bootstrap servlet.

Take a look at https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-Jersey-2.X-Project-Setup-1.5#using-a-servlet:

The line:

        beanConfig.setResourcePackage("io.swagger.resources");

should actually point to your resource packages. The value given there is just an example.

That would tell swagger-core which packages to scan for resources and read the annotations.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[David Rickard]

This is my BootstrapServlet:

public class SwaggerBootstrap extends HttpServlet

{

  public SwaggerBootstrap()

  {

    super();

  }

  @Override

  public void init( ServletConfig config )

    throws ServletException

  {

    super.init( config );

    BeanConfig beanConfig = new BeanConfig();

    beanConfig.setVersion( "1.0.0" );

    beanConfig.setSchemes( new String[] { "https" } );

    beanConfig.setHost( "webservices-test.library.ucla.edu" );

    beanConfig.setBasePath( "/pss" );

    beanConfig.setResourcePackage( "edu.ucla.library.libservices.pubstats.web.service" ); 

    beanConfig.setScan( true );

  }

}

We are pointing to our resource classes.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
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/tPHJTra2Tpw/unsubscribe.
To unsubscribe from this group and all its topics, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

[Ron Ratovsky]

Gotcha. Are your resources annotated with @Api?

--

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
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/tPHJTra2Tpw/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/d/optout.

 

--

You received this message because you are subscribed to the Google Groups "Swagger" group.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

[David Rickard]

No. they're not... And FWIW there's no reference to @Api on the Swagger Core tutorial page...

--

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
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/tPHJTra2Tpw/unsubscribe.

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

For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
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/tPHJTra2Tpw/unsubscribe.

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

[Ron Ratovsky]

Yeah, I understand how it can be confusing. That specific page is more about how to configure the app, less about how to use the annotations.

Swagger-core uses the annotations to build up the description, either JAX-RS’s or its own. We need some of those annotations to hint on things.

Take a look at https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X please.

 

 

 

From: <swagger-sw...@googlegroups.com> on behalf of David Rickard <dricka...@gmail.com>
Reply-To: "swagger-sw...@googlegroups.com" <swagger-sw...@googlegroups.com>
Date: Wednesday, 31 May 2017 at 13:02
To: "swagger-sw...@googlegroups.com" <swagger-sw...@googlegroups.com>
Subject: Re: Swagger Core Scanning Web App But Not Generating Documentation

 

No. they're not... And FWIW there's no reference to @Api on the Swagger Core tutorial page...

 

--

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
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/tPHJTra2Tpw/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/d/optout.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
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/tPHJTra2Tpw/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/d/optout.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

[David Rickard]

Added annotations to the service classes and hey presto!--we have useful output from Swagger.

Maybe a note should be added to the end of the setup guide advising users to read the annotations guide?  Just a thought...

On Wed, May 31, 2017 at 1:16 PM, Ron Ratovsky <r...@swagger.io> wrote:

Yeah, I understand how it can be confusing. That specific page is more about how to configure the app, less about how to use the annotations.

Swagger-core uses the annotations to build up the description, either JAX-RS’s or its own. We need some of those annotations to hint on things.

Take a look at https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X please.

 

 

 

From: <swagger-swaggersocket@googlegroups.com> on behalf of David Rickard <dricka...@gmail.com>
Reply-To: "swagger-swaggersocket@googlegroups.com" <swagger-swaggersocket@googlegroups.com>
Date: Wednesday, 31 May 2017 at 13:02

To: "swagger-swaggersocket@googlegroups.com" <swagger-swaggersocket@googlegroups.com>

--

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
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/tPHJTra2Tpw/unsubscribe.

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

For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
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/tPHJTra2Tpw/unsubscribe.

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

For more options, visit https://groups.google.com/d/optout.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggersocket+unsub...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
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/tPHJTra2Tpw/unsubscribe.

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

[Ron Ratovsky]

Fair point, done. Thanks for your feedback.

 

 

 

From: <swagger-sw...@googlegroups.com> on behalf of David Rickard <dricka...@gmail.com>
Reply-To: "swagger-sw...@googlegroups.com" <swagger-sw...@googlegroups.com>
Date: Wednesday, 31 May 2017 at 13:53
To: "swagger-sw...@googlegroups.com" <swagger-sw...@googlegroups.com>
Subject: Re: Swagger Core Scanning Web App But Not Generating Documentation

 

Added annotations to the service classes and hey presto!--we have useful output from Swagger.

Maybe a note should be added to the end of the setup guide advising users to read the annotations guide?  Just a thought...

On Wed, May 31, 2017 at 1:16 PM, Ron Ratovsky <r...@swagger.io> wrote:

Yeah, I understand how it can be confusing. That specific page is more about how to configure the app, less about how to use the annotations.

Swagger-core uses the annotations to build up the description, either JAX-RS’s or its own. We need some of those annotations to hint on things.

Take a look at https://github.com/swagger-api/swagger-core/wiki/Annotations-1.5.X please.

 

 

 

From: <swagger-sw...@googlegroups.com> on behalf of David Rickard <dricka...@gmail.com>
Reply-To: "swagger-sw...@googlegroups.com" <swagger-sw...@googlegroups.com>
Date: Wednesday, 31 May 2017 at 13:02

To: "swagger-sw...@googlegroups.com" <swagger-sw...@googlegroups.com>

--

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
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/tPHJTra2Tpw/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/d/optout.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
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/tPHJTra2Tpw/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/d/optout.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--
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/tPHJTra2Tpw/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/d/optout.

--
You received this message because you are subscribed to the Google Groups "Swagger" group.

To unsubscribe from this group and stop receiving emails from it, send an email to swagger-swaggers...@googlegroups.com.