Separating API Docs into multiple pages

[drm...@g.rit.edu]

Hello, recently I've been working on a Swagger doc for my company's new API. One difficulty I am having is separating our 5 sub projects into their own swagger page. Let me explain what we have (I'll use filler names for things just incase I shouldn't be posting specifics)

Lets say we have 3 projects: Apple, Orange and Grape.

We have 4 different html pages. One for each project and a main index page. We have three different servlets named Apple-swagger, Orange-swagger and Grape-swagger. Each one of these are loaded into our web.xml as follows:

  <servlet>

    <servlet-name>Apple</servlet-name>

    <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>

    <load-on-startup>1</load-on-startup>

  </servlet>

  <servlet-mapping>

    <servlet-name>Apple</servlet-name>

    <url-pattern>/Apple-swagger/*</url-pattern>

  </servlet-mapping>

We also have three .properties files in our resource directory that contain the following:

documentation.services.basePath=http://0.0.0.0:8081/Apple-swagger

documentation.services.version=1.0

In the index html, we link to each of the other html pages which runs javascript to load the swagger doc on the page. We have not been able to get multiple pages loaded simultaneously. Each page says "Cant read swagger json...." Now, we're not even sure if this is possible because the pet store example is using one page for everything but we felt like this was possible. So any help would be highly appreciated.

[tony tam]

Hi, it's actually easy to do what you're after, since (for better or worse), swagger's library is loaded as a singleton across the servlet.  That means you can have different resource listings for each servlet.

If you want a single resource listing for all servlets, you can load swagger libraries in the parent classloader (jetty's ./lib) and it can access all the api annotations.  Does that help?

[drm...@g.rit.edu]

Not really understanding what you mean. Unfortunately I don't have much experience with a lot of this stuff. The issues seems to be if I set the jetty configuration to path "/swagger" and port 8080, then I can never load anything to say "/apple" even though they both have their own property files, servlet, and html file. Not sure what the parent classloader is, if you could explain a little more that would be great.

[tony tam]

OK, let me back up.  Are you using JAX-RS or straight servlets using swagger-servlet?

[drm...@g.rit.edu]

We're using straight servlets on swagger

[tony tam]

ok great.  then this is how it's done.

The swagger-servlet code will aggregate your resources into a single swagger instance.  For example:

ServletA.java

@Api(value = "/fruits/apple", description = "gets some data from a servlet")

public class ServletA extends HttpServlet { // ...

ServletB.java

@Api(value = "/fruits/orange", description = "gets some data from a servlet")

public class ServletB extends HttpServlet { // ...

ServletB.java

@Api(value = "/fruits/grape", description = "gets some data from a servlet")

public class ServletC extends HttpServlet { // ...

Now Swagger will build a resource listing that contains 3 different path elements.

You would then mount the swagger servlet in your web.xml:

https://github.com/wordnik/swagger-core/blob/master/samples/scala-servlet/src/main/webapp/WEB-INF/web.xml#L36-L43

<url-pattern>/api-docs/*</url-pattern>

And you should be able to access the docs with the swagger ui as such:

http://localhost:8080/api-docs

This would show all three servlets' info.  If you want just a single servlet to be in the ui, you would simply point it directly to that servlet in the url:

https://github.com/wordnik/swagger-ui/blob/master/dist/index.html#L22

becomes something like this:

url: "http://localhost:8080/api-docs/fruits/apple",

I think that'll do it.  Give it a shot and report back--the short answer is, your servlet context will have a single swagger instance, but you can access the apis directly from the UI if you want to see them in isolation.

[drm...@g.rit.edu]

Hey, I'm really sorry I think I was incorrect on your last question after seeing your answer. I guess I'm not too good at this haha.

After doing some research into JAXRS, I think we might be using that because the servlet code in your answer is not consistent with the formatting of ours. Our servlet files are .xml files that seem to just be scanning the project for the classes with in the project. All of our swagger annotations are in the .java classes for the controller endpoints. I think the second half of the instructions are still valid as I've been messing with those setting a lot over the past week.

Sorry again about that but I really appreciate your help. Being an intern can be tough :)

[Ron]

Just to be sure, can you share the code of one of your controllers? Based on the web.xml you shared, you may actually be using Spring-MVC instead.
That way, we could direct you accordingly.

--
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/groups/opt_out.

[drm...@g.rit.edu]

Oh, I'm embarrassed...I'm definitely using Spring MVC I thought this google group would apply but I guess I'm wrong 

[Ron]

Keep in mind that just because you use Spring, it doesn't mean you necessarily use spring mvc. Which swagger library do you use?

On Fri, Feb 28, 2014 at 5:45 PM, <drm...@g.rit.edu> wrote:

Oh, I'm embarrassed...I'm definitely using Spring MVC I thought this google group would apply but I guess I'm wrong 

--

[drm...@g.rit.edu]

This is in our pom file

<dependency>

<groupId>com.mangofactory</groupId>

<artifactId>swagger-springmvc</artifactId>

<version>0.6.6</version>

</dependency>

 

[Ron]

Then yes, you're using Spring-MVC. I'm not entirely sure what capabilities that library offers. Maybe it would be better to open an issue on that project.

--