RSS

REST API Documentation with Swagger

25 Mar

This is going to focus REST API documentation with Swagger. We know that REST APIs are very popular with modern world technology and most of the technology solutions came up with REST Implementations. Developers who are involved with the REST APIs development and they have kind of problem like how to document the REST APIs and how to simply expose those REST APIs to the end users. Swagger is good solution for above explained problem. So lets talk about swagger integration to the JAX-RS API. I think that you are familiar with the JAVA JAX-RS implementations. If not you have to get some knowledge about JAX-RS implementation.

1. You have to add swagger maven artifact to your project.

2. Secondly you have to mentioned the base path on your web.xml. This URL will be used as backend service call from swagger-ui

3. Finally you have to annotate your REST-APIs by swagger annotations. You can get total idea from following code snippets.

4. Then you have to get the swagger-ui and host it on your local tomcat.

5. Now you can simply view and invoke the REST APIs which is developed by you by using the Swagger UI.

test

test2

Advertisements
 
24 Comments

Posted by on March 25, 2014 in java

 

Tags: , , ,

24 responses to “REST API Documentation with Swagger

  1. fred

    July 2, 2014 at 2:19 pm

    Hi,

    It’s very clear, and very helpful and good presented.
    So, i have a question: As i readed in some swagger descritption, that we can create REST services with it. Is it realy possible to create services with it?
    Thanks

     
    • malalanayake

      July 2, 2014 at 2:27 pm

      Actually swagger is a documentation API. You cannot creat rest API within it but you can do the nice documentation for your rest API. Then you can expose the documentation to the clients without effort. I hope you got the answer for your question.

       
    • bebraw

      January 12, 2015 at 10:04 am

      There are tools that can deal with aspects such as request/response validation for you. swagger-tools is a library for Node.js that achieves exactly this. You can likely find similar libraries for other environments.

       
  2. rahul

    November 11, 2014 at 1:43 pm

    i have managed to insert swagger annotations to the resource. but swagger ui is giving me 404.

    my web.xml as :

    DefaultJaxrsConfig
    com.wordnik.swagger.jaxrs.config.DefaultJaxrsConfig

    api.version
    3

    swagger.api.basepath
    http://localhost:8080/swaggertest/rest

    2

    Jersey Servlet
    /rest/*

     
  3. PA

    April 3, 2015 at 2:08 pm

    I see Spring Framework has its own dependendency
    http://mvnrepository.com/artifact/com.mangofactory/swagger-springmvc

    com.mangofactory
    swagger-springmvc
    1.0.2

    I’m trying to redeveloped your code to use Spring’s Swagger Dependency but facing some issues.

    Could you please update the code to use Spring’s dependency?

     
  4. Kavindu Narathota

    April 22, 2015 at 11:57 am

    Hi Dinuka,
    First of all thank you for this article.
    I’m having some difficulties in integrating and configuring Swagger with my REST app. In here I think you have placed your swagger-ui folder externally and access it. But in a different article (http://goo.gl/pjJBpH) i came a cross with a part saying that “directory dist must be copied to your src/main/webapp”

    I’ve tried this method and failed to execute it.

    so can you please give a comment on how to correctly integrate swagger with REST

    Thank you.

     
    • malalanayake

      April 22, 2015 at 1:38 pm

      Hi Kavindu,

      I think you are talking about Swagger-UI components. Usually we don’t deliver the Swagger-UI components with our project. So what I did I hosted the Swagger-UI project differently and gave my api URL to the UI project. If you want to expose the UI project inside your project you can place the UI components on webapp as you said and then expose that component through your web.xml or through the web service.

      Ex/ Finally you have to have the way to access your Swagger UI component through public URL.

       
  5. tech user

    July 7, 2015 at 4:38 am

    Hi if I want Swagger as a service, i.e I can point to different rest services deployed in different war. Is this achievable by swagger if yes , then how….

     
  6. Prashanth Bhat

    July 30, 2015 at 6:41 am

    Any extra configuration require for rest-easy rest implementation? i have added DefaultJaxrsConfig to my web.xml but i am not able to access /api/api-docs

    Resteasy
    org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher

    javax.ws.rs.Application
    com.my.myApplication

    resteasy.servlet.mapping.prefix
    /api

    Resteasy
    /api/*

    resteasy.scan
    true

    DefaultJaxrsConfig
    io.swagger.jaxrs.config.DefaultJaxrsConfig

    api.version
    3

    swagger.api.basepath
    http://10.220.27.99:8080/api

    2

    i have also added swagger ui into tomcat i am able to access ui but rest APIs

     
  7. Irfan nasim

    October 13, 2015 at 5:59 am

    not running, giving error Marking servlet DefaultJaxrsConfig as unavailable, java.lang.ClassNotFoundException: com.wordnik.swagger.jaxrs.config.DefaultJaxrsConfig

     
    • malalanayake

      October 13, 2015 at 1:48 pm

      I think you might missing swagger jars in your classpath.

       
  8. Irfan nasim

    October 13, 2015 at 1:55 pm

    not missing, it is maven project. automatically it is including the jars

     
  9. Irfan nasim

    October 13, 2015 at 2:13 pm

    I am getting this error while running the application.
    Oct 13, 2015 7:10:15 PM org.apache.catalina.core.ApplicationContext log
    INFO: Marking servlet Jersey2Config as unavailable
    Oct 13, 2015 7:10:15 PM org.apache.catalina.core.StandardContext loadOnStartup
    SEVERE: Servlet /PatientApp threw load() exception
    java.lang.ClassNotFoundException: io.swagger.jersey.config.JerseyJaxrsConfig
    at org.apache.catalina.loader.WebappClassLoader.loadClass(WebappClassLoader.java:1720)
    at org.apache.catalina.loader.WebappClassLoader.loadClass(WebappClassLoader.java:1571)
    at org.apache.catalina.core.DefaultInstanceManager.loadClass(DefaultInstanceManager.java:506)
    at org.apache.catalina.core.DefaultInstanceManager.loadClassMaybePrivileged(DefaultInstanceManager.java:488)
    at org.apache.catalina.core.DefaultInstanceManager.newInstance(DefaultInstanceManager.java:115)
    at org.apache.catalina.core.StandardWrapper.loadServlet(StandardWrapper.java:1148)
    at org.apache.catalina.core.StandardWrapper.load(StandardWrapper.java:1087)
    at org.apache.catalina.core.StandardContext.loadOnStartup(StandardContext.java:5231)
    at org.apache.catalina.core.StandardContext.startInternal(StandardContext.java:5518)
    at org.apache.catalina.util.LifecycleBase.start(LifecycleBase.java:150)
    at org.apache.catalina.core.ContainerBase.addChildInternal(ContainerBase.java:901)
    at org.apache.catalina.core.ContainerBase.addChild(ContainerBase.java:877)
    at org.apache.catalina.core.StandardHost.addChild(StandardHost.java:649)
    at org.apache.catalina.startup.HostConfig.manageApp(HostConfig.java:1760)
    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:57)
    at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
    at java.lang.reflect.Method.invoke(Method.java:606)
    at org.apache.tomcat.util.modeler.BaseModelMBean.invoke(BaseModelMBean.java:301)
    at com.sun.jmx.interceptor.DefaultMBeanServerInterceptor.invoke(DefaultMBeanServerInterceptor.java:819)
    at com.sun.jmx.mbeanserver.JmxMBeanServer.invoke(JmxMBeanServer.java:801)
    at org.apache.catalina.mbeans.MBeanFactory.createStandardContext(MBeanFactory.java:618)
    at org.apache.catalina.mbeans.MBeanFactory.createStandardContext(MBeanFactory.java:565)
    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:57)
    at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
    at java.lang.reflect.Method.invoke(Method.java:606)
    at org.apache.tomcat.util.modeler.BaseModelMBean.invoke(BaseModelMBean.java:301)
    at com.sun.jmx.interceptor.DefaultMBeanServerInterceptor.invoke(DefaultMBeanServerInterceptor.java:819)
    at com.sun.jmx.mbeanserver.JmxMBeanServer.invoke(JmxMBeanServer.java:801)
    at javax.management.remote.rmi.RMIConnectionImpl.doOperation(RMIConnectionImpl.java:1487)
    at javax.management.remote.rmi.RMIConnectionImpl.access$300(RMIConnectionImpl.java:97)
    at javax.management.remote.rmi.RMIConnectionImpl$PrivilegedOperation.run(RMIConnectionImpl.java:1328)
    at javax.management.remote.rmi.RMIConnectionImpl.doPrivilegedOperation(RMIConnectionImpl.java:1420)
    at javax.management.remote.rmi.RMIConnectionImpl.invoke(RMIConnectionImpl.java:848)
    at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:57)
    at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
    at java.lang.reflect.Method.invoke(Method.java:606)
    at sun.rmi.server.UnicastServerRef.dispatch(UnicastServerRef.java:322)
    at sun.rmi.transport.Transport$1.run(Transport.java:177)
    at sun.rmi.transport.Transport$1.run(Transport.java:174)
    at java.security.AccessController.doPrivileged(Native Method)
    at sun.rmi.transport.Transport.serviceCall(Transport.java:173)
    at sun.rmi.transport.tcp.TCPTransport.handleMessages(TCPTransport.java:556)
    at sun.rmi.transport.tcp.TCPTransport$ConnectionHandler.run0(TCPTransport.java:811)
    at sun.rmi.transport.tcp.TCPTransport$ConnectionHandler.run(TCPTransport.java:670)
    at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1145)
    at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:615)
    at java.lang.Thread.run(Thread.java:724)

    And next question is where swagger_ui have to paste and what portion / folder of this paste?

     
  10. Irfan nasim

    October 13, 2015 at 2:22 pm

    Hwo to pass Authorization object to filter?

     
  11. valentino

    March 6, 2016 at 5:49 pm

    Can you put the sample project in github

     
  12. M J S Prasad

    May 31, 2016 at 5:51 am

    What is a base path here…, Currently my Application is running in http://localhost:9090/api, is this Base path?

     
  13. vinay

    August 17, 2016 at 12:02 pm

    @Api annotation causing Caused By: java.lang.NoSuchMethodError: com.fasterxml.jackson.databind.AnnotationIntrospector.findPropertyIndex(Lcom/fasterxml/jackson/databind/introspect/Annotated;)Ljava/lang/Integer;

    How to deal with this ,m not using maven in my project.

     
    • malalanayake

      August 17, 2016 at 12:28 pm

      You are missing some of the indirect dependancies. Just search the class name on internet and find a Jars for that.

       
  14. Raji

    November 18, 2016 at 8:43 pm

    Where is the swagger json file stored?

     
  15. Kishore

    November 30, 2016 at 1:19 pm

    I am trying to configure Swagger ui with Apache CXF RESTful service which does not have web.xml file and webcontent & WEB-INF folders. Through Apache camel service is hitting now. Any one help to integrate swagger with above conditions with step by step. I am new to services, Apache camel, Maven and swagger. 1) I added two dependencies in pom.xml file 2) created one swagger configure file in one package(.java file) 3) I dont have web.xml file so dont know how to format url in browser I used http://localhost:{portno]/projectname/api-docs http://localhost:{portno]/projectname/swagger.json I did not get result(json) for any url. Please help me to configure and form url

     
  16. kiran

    March 1, 2017 at 1:12 pm

    Hi, Thanks for nice explanation. I have one question, is there any way to seperate swagger api-docs for each rest service call seperately

     
  17. Madhukar Pvsn

    April 4, 2017 at 4:52 am

    can this be configured for a standalone java rest application?

     
  18. Asheesh Kumar

    July 5, 2017 at 12:33 pm

    hi.. malalanayake,

    i want to know could i design the swagger doc for REST API with struts2. if yes could you mail the steps.

     
  19. mashkurali Marchawala

    July 7, 2017 at 6:55 am

    Hi, I am using resteasy with swagger, and my problem is that I am getting all the get requests in swagger.json file where as not getting any put, post or delete requests. I am using resteasy sample projects from https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-RESTEasy-2.X-Project-Setup-1.5..

    When I hit localhost:80002/api/swagger.json, it shows me only get responses.
    Let me know if I am missing anything..

     

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

 
%d bloggers like this: