Skip to content

Instantly share code, notes, and snippets.

@anirtek

anirtek/Swagger Setup for Embedded Jetty Server.md

Forked from nosmokingpistol/Swagger Setup for Embedded Jetty Server.md
Last active April 21, 2021 04:19
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save anirtek/08c27e11ae3b0b87f8e4560a38351a48 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save anirtek/08c27e11ae3b0b87f8e4560a38351a48 to your computer and use it in GitHub Desktop.
Download ZIP

Revisions

  1. Aniruddha Tekade revised this gist Apr 21, 2021. 1 changed file with 2 additions and 2 deletions.
    4 changes: 2 additions & 2 deletions Swagger Setup for Embedded Jetty Server.md
    View file
    Original file line number Diff line number Diff line change
    @@ -59,7 +59,7 @@ First, to add the Swagger package scanning classes. Usually one would add them t
    }
    }

    ##Add the Swagger package scanning servlet##
    ## Add the Swagger package scanning servlet ##
    Now, to configure and initialize Swagger. Based on [these](https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-Jersey-1.X-Project-Setup-1.5#configure-and-initialize-swagger) instructions, you'll now manually create and add the Swagger servlet. The path provided for the Swagger servlet is irrelevant, as it is not actually accessed through this path. **However, make sure it does not collide with any of your other resource paths!**

    public class MyServer {
    @@ -87,7 +87,7 @@ Now, to configure and initialize Swagger. Based on [these](https://github.com/sw

    Now, when you navigate to `http://<host>:8080/api/swagger.json`, Swagger will generate a JSON response detailing your resource paths, their parameters, and their responses.

    ##Package the Swagger-UI static HTML5 content with your server##
    ## Package the Swagger-UI static HTML5 content with your server ##
    However, most people prefer a more human readable method -- so we will now package the [Swagger-UI](https://github.com/swagger-api/swagger-ui) HTML5 project with your server.

    To your pom.xml, you need to add the ability to download and and then copy the Swagger-UI static resources to your project's resources folder. That way when you package and run your server eventually via `java -cp <libs> MyServer.class`, it will be able to display the Swagger UI at `http:://<host>:8080/`.
  2. Aniruddha Tekade revised this gist Apr 21, 2021. 1 changed file with 1 addition and 1 deletion.
    2 changes: 1 addition & 1 deletion Swagger Setup for Embedded Jetty Server.md
    View file
    Original file line number Diff line number Diff line change
    @@ -38,7 +38,7 @@ In this example, the servlet serving the API is initialized as a ServletContaine

    ServletHolder apiServlet = context.addServlet(new MyServlet(), "/path/*");

    ## Add the package scanning packages to your servlets which will serve your REST API##
    ## Add the package scanning packages to your servlets which will serve your REST API ##

    First, to add the Swagger package scanning classes. Usually one would add them to the web.xml like [this](https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-Jersey-1.X-Project-Setup-1.5#package-scanning--concrete-class-selection). In your embedded Jetty servlet setup, you are setting the packages you are serving via the `"com.sun.jersey.config.property.packages"` property. So, add the `io.swagger.jaxrs.json;io.swagger.jaxrs.listing` packages to your servlet setup, like so:

  3. Aniruddha Tekade revised this gist Apr 21, 2021. 1 changed file with 2 additions and 1 deletion.
    3 changes: 2 additions & 1 deletion Swagger Setup for Embedded Jetty Server.md
    View file
    Original file line number Diff line number Diff line change
    @@ -38,7 +38,8 @@ In this example, the servlet serving the API is initialized as a ServletContaine

    ServletHolder apiServlet = context.addServlet(new MyServlet(), "/path/*");

    ##Add the package scanning packages to your servlets which will serve your REST API##
    ## Add the package scanning packages to your servlets which will serve your REST API##

    First, to add the Swagger package scanning classes. Usually one would add them to the web.xml like [this](https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-Jersey-1.X-Project-Setup-1.5#package-scanning--concrete-class-selection). In your embedded Jetty servlet setup, you are setting the packages you are serving via the `"com.sun.jersey.config.property.packages"` property. So, add the `io.swagger.jaxrs.json;io.swagger.jaxrs.listing` packages to your servlet setup, like so:

    public class MyServer {
  4. @nosmokingpistol nosmokingpistol revised this gist Sep 14, 2015. 1 changed file with 1 addition and 1 deletion.
    2 changes: 1 addition & 1 deletion Swagger Setup for Embedded Jetty Server.md
    View file
    Original file line number Diff line number Diff line change
    @@ -86,7 +86,7 @@ Now, to configure and initialize Swagger. Based on [these](https://github.com/sw

    Now, when you navigate to `http://<host>:8080/api/swagger.json`, Swagger will generate a JSON response detailing your resource paths, their parameters, and their responses.

    ##Package the Swagger-UI static HTML5 content with your server## {add-swagger-ui}
    ##Package the Swagger-UI static HTML5 content with your server##
    However, most people prefer a more human readable method -- so we will now package the [Swagger-UI](https://github.com/swagger-api/swagger-ui) HTML5 project with your server.

    To your pom.xml, you need to add the ability to download and and then copy the Swagger-UI static resources to your project's resources folder. That way when you package and run your server eventually via `java -cp <libs> MyServer.class`, it will be able to display the Swagger UI at `http:://<host>:8080/`.
  5. @nosmokingpistol nosmokingpistol revised this gist Sep 14, 2015. 1 changed file with 2 additions and 2 deletions.
    4 changes: 2 additions & 2 deletions Swagger Setup for Embedded Jetty Server.md
    View file
    Original file line number Diff line number Diff line change
    @@ -84,12 +84,12 @@ Now, to configure and initialize Swagger. Based on [these](https://github.com/sw
    }
    }

    Now, when you navigate to `http://<host>:<port>/api/swagger.json`, Swagger will generate a JSON response detailing your resource paths, their parameters, and their responses.
    Now, when you navigate to `http://<host>:8080/api/swagger.json`, Swagger will generate a JSON response detailing your resource paths, their parameters, and their responses.

    ##Package the Swagger-UI static HTML5 content with your server## {add-swagger-ui}
    However, most people prefer a more human readable method -- so we will now package the [Swagger-UI](https://github.com/swagger-api/swagger-ui) HTML5 project with your server.

    To your pom.xml, you need to add the ability to download and and then copy the Swagger-UI static resources to your project's resources folder. That way when you package and run your server eventually via `java -cp <libs> MyServer.class`, it will be able to display the Swagger UI at `http:://<host>:<port>/`.
    To your pom.xml, you need to add the ability to download and and then copy the Swagger-UI static resources to your project's resources folder. That way when you package and run your server eventually via `java -cp <libs> MyServer.class`, it will be able to display the Swagger UI at `http:://<host>:8080/`.

    Similar to [here](https://github.com/swagger-api/swagger-samples/blob/master/java/java-jersey-jaxrs/pom.xml), we will add the following lines to our pom.xml, in the `<build></build>` portion:

  6. @nosmokingpistol nosmokingpistol revised this gist Sep 14, 2015. 1 changed file with 14 additions and 1 deletion.
    15 changes: 14 additions & 1 deletion Swagger Setup for Embedded Jetty Server.md
    View file
    Original file line number Diff line number Diff line change
    @@ -17,6 +17,7 @@ Let's start with a basic server class, adapted from the Eclipse tutorial above.
    context.setContextPath("/");
    server.setHandler(context);
    // Setup API resources
    ServletHolder apiServlet = context.addServlet(ServletContainer.class, "/api/*");
    apiServlet.setInitOrder(1);
    apiServlet.setInitParameter("com.sun.jersey.config.property.packages", "com.api.resources");
    @@ -68,10 +69,12 @@ Now, to configure and initialize Swagger. Based on [these](https://github.com/sw
    context.setContextPath("/");
    server.setHandler(context);
    // Setup API resources
    ServletHolder apiServlet = context.addServlet(ServletContainer.class, "/api/*");
    apiServlet.setInitOrder(1);
    apiServlet.setInitParameter("com.sun.jersey.config.property.packages", "com.api.resources;io.swagger.jaxrs.json;io.swagger.jaxrs.listing");
    // Setup Swagger servlet
    ServletHolder swaggerServlet = context.addServlet(DefaultJaxrsConfig.class, "/swagger-core");
    swaggerServlet.setInitOrder(2);
    swaggerServlet.setInitParameter("api.version", "1.0.0");
    @@ -151,15 +154,25 @@ Now, you have to point your ServletContextHandler to these static resources. Beg
    context.setContextPath("/");
    server.setHandler(context);

    // Setup API resources
    ServletHolder apiServlet = context.addServlet(ServletContainer.class, "/api/*");
    apiServlet.setInitOrder(1);
    apiServlet.setInitParameter("com.sun.jersey.config.property.packages", "com.api.resources;io.swagger.jaxrs.json;io.swagger.jaxrs.listing");

    // Setup Swagger servlet
    ServletHolder swaggerServlet = context.addServlet(DefaultJaxrsConfig.class, "/swagger-core");
    swaggerServlet.setInitOrder(2);
    swaggerServlet.setInitParameter("api.version", "1.0.0");

    // Setup Swagger-UI static resources
    String resourceBasePath = ServicesRunner.class.getResource("/webapp").toExternalForm();
    context.setWelcomeFiles(new String[] {"index.html"});
    context.setResourceBase(resourceBasePath);
    context.addServlet(new ServletHolder(new DefaultServlet()), "/*");

    server.start();
    server.join();
    }
    }
    }

    Now, when you start up your server via `usr/bin/java -cp <libs> MyServer`, you should be able to navigate to `http://<host>:8080` and see the Swagger-UI welcome page, similar to [this demo page](http://petstore.swagger.io/). Enter your api Swagger paths (e.g. `http://<host>:8080/api/swagger.json`) in order to see your API Resources Swagger-fied.
  7. @nosmokingpistol nosmokingpistol revised this gist Sep 14, 2015. 1 changed file with 27 additions and 3 deletions.
    30 changes: 27 additions & 3 deletions Swagger Setup for Embedded Jetty Server.md
    View file
    Original file line number Diff line number Diff line change
    @@ -90,7 +90,7 @@ To your pom.xml, you need to add the ability to download and and then copy the S

    Similar to [here](https://github.com/swagger-api/swagger-samples/blob/master/java/java-jersey-jaxrs/pom.xml), we will add the following lines to our pom.xml, in the `<build></build>` portion:

    <!-- For development, download the Swagger-UI project -->
    <!-- Download the Swagger-UI project -->
    <build>
    <plugins>
    ...
    @@ -114,8 +114,7 @@ Similar to [here](https://github.com/swagger-api/swagger-samples/blob/master/jav
    </executions>
    </plugin>
    <!-- Load the Swagger-UI components into the src/main/webapp/ directory to enable
    viewing/testing of the API routes. Accessible at http://<host>:<port>/swagger. Host
    and port are determined by the womply.default.xml. -->
    viewing/testing of the API routes. Accessible at http://<host>:<port>/swagger. -->
    <plugin>
    <artifactId>maven-resources-plugin</artifactId>
    <version>2.7</version>
    @@ -139,3 +138,28 @@ Similar to [here](https://github.com/swagger-api/swagger-samples/blob/master/jav
    </plugin>
    </plugins>
    </build>

    When you run `mvn clean package` on your project, this will first download the Swagger-UI into `target` folder. Then, the `dist` folder of the Swagger-UI project is copied into the `/resources/webapp` folder of your main project. When compiled, the `webapp` folder will then appear in `target/classes`, and be accessible to your compiled and running server JAR.

    Now, you have to point your ServletContextHandler to these static resources. Begin by using your `MyServer` class to find the resource, then set the welcome file to be the name of the desired HTML file (in this case, 'index.html'). Update your ServletContextHandler's resource base path to point to the static resources. Finally, add a DefaultServlet to serve these static resources. **This DefaultServlet must be the last servlet added to your ServletContextHandler.**

    public class MyServer {
    public static void main(String[] args) throws Exception
    {
    Server server = new Server(8080);
    ServletContextHandler context = new ServletContextHandler(ServletContextHandler.SESSIONS);
    context.setContextPath("/");
    server.setHandler(context);

    ServletHolder apiServlet = context.addServlet(ServletContainer.class, "/api/*");
    apiServlet.setInitOrder(1);
    apiServlet.setInitParameter("com.sun.jersey.config.property.packages", "com.api.resources;io.swagger.jaxrs.json;io.swagger.jaxrs.listing");

    String resourceBasePath = ServicesRunner.class.getResource("/webapp").toExternalForm();
    context.setWelcomeFiles(new String[] {"index.html"});
    context.setResourceBase(resourceBasePath);
    context.addServlet(new ServletHolder(new DefaultServlet()), "/*");
    server.start();
    server.join();
    }
    }
  8. @nosmokingpistol nosmokingpistol revised this gist Sep 14, 2015. 1 changed file with 60 additions and 6 deletions.
    66 changes: 60 additions & 6 deletions Swagger Setup for Embedded Jetty Server.md
    View file
    Original file line number Diff line number Diff line change
    @@ -3,9 +3,9 @@ In setting up a Jetty server with Jersey servlets, you may choose to use an embe

    In the Swagger Core setup, the current official recommendations involve an Application class, or a web.xml, neither of which are used in an embedded Jetty server setup. To add Swagger to your embedded Jetty Server, you must do 3 things:

    1. [Add the package scanning packages to your servlets which will serve your REST API.](add-package-scanning)
    2. [Add the Swagger package scanning servlet.](add-swagger-servlet)
    3. [Package the Swagger-UI static HTML5 content with your server](add-swagger-ui)
    1. Add the package scanning packages to your servlets which will serve your REST API.
    2. Add the Swagger package scanning servlet.
    3. Package the Swagger-UI static HTML5 content with your server

    Let's start with a basic server class, adapted from the Eclipse tutorial above.

    @@ -37,7 +37,7 @@ In this example, the servlet serving the API is initialized as a ServletContaine

    ServletHolder apiServlet = context.addServlet(new MyServlet(), "/path/*");

    ##Add the package scanning packages to your servlets which will serve your REST API## {add-package-scanning}
    ##Add the package scanning packages to your servlets which will serve your REST API##
    First, to add the Swagger package scanning classes. Usually one would add them to the web.xml like [this](https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-Jersey-1.X-Project-Setup-1.5#package-scanning--concrete-class-selection). In your embedded Jetty servlet setup, you are setting the packages you are serving via the `"com.sun.jersey.config.property.packages"` property. So, add the `io.swagger.jaxrs.json;io.swagger.jaxrs.listing` packages to your servlet setup, like so:

    public class MyServer {
    @@ -56,7 +56,8 @@ First, to add the Swagger package scanning classes. Usually one would add them t
    server.join();
    }
    }
    ##Add the Swagger package scanning servlet## {add-swagger-servlet}

    ##Add the Swagger package scanning servlet##
    Now, to configure and initialize Swagger. Based on [these](https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-Jersey-1.X-Project-Setup-1.5#configure-and-initialize-swagger) instructions, you'll now manually create and add the Swagger servlet. The path provided for the Swagger servlet is irrelevant, as it is not actually accessed through this path. **However, make sure it does not collide with any of your other resource paths!**

    public class MyServer {
    @@ -81,7 +82,60 @@ Now, to configure and initialize Swagger. Based on [these](https://github.com/sw
    }

    Now, when you navigate to `http://<host>:<port>/api/swagger.json`, Swagger will generate a JSON response detailing your resource paths, their parameters, and their responses.

    ##Package the Swagger-UI static HTML5 content with your server## {add-swagger-ui}
    However, most people prefer a more human readable method -- so we will now package the [Swagger-UI](https://github.com/swagger-api/swagger-ui) HTML5 project with your server.

    To your pom.xml, you need to add the ability to download and
    To your pom.xml, you need to add the ability to download and and then copy the Swagger-UI static resources to your project's resources folder. That way when you package and run your server eventually via `java -cp <libs> MyServer.class`, it will be able to display the Swagger UI at `http:://<host>:<port>/`.

    Similar to [here](https://github.com/swagger-api/swagger-samples/blob/master/java/java-jersey-jaxrs/pom.xml), we will add the following lines to our pom.xml, in the `<build></build>` portion:

    <!-- For development, download the Swagger-UI project -->
    <build>
    <plugins>
    ...
    <plugin>
    <groupId>com.googlecode.maven-download-plugin</groupId>
    <artifactId>download-maven-plugin</artifactId>
    <version>1.2.1</version>
    <executions>
    <execution>
    <id>swagger-ui</id>
    <phase>validate</phase>
    <goals>
    <goal>wget</goal>
    </goals>
    <configuration>
    <url>https://github.com/swagger-api/swagger-ui/archive/v2.1.1.tar.gz</url>
    <unpack>true</unpack>
    <outputDirectory>${project.build.directory}</outputDirectory>
    </configuration>
    </execution>
    </executions>
    </plugin>
    <!-- Load the Swagger-UI components into the src/main/webapp/ directory to enable
    viewing/testing of the API routes. Accessible at http://<host>:<port>/swagger. Host
    and port are determined by the womply.default.xml. -->
    <plugin>
    <artifactId>maven-resources-plugin</artifactId>
    <version>2.7</version>
    <executions>
    <execution>
    <id>copy-resources</id>
    <phase>initialize</phase>
    <goals>
    <goal>copy-resources</goal>
    </goals>
    <configuration>
    <outputDirectory>${basedir}/src/main/resources/webapp</outputDirectory>
    <resources>
    <resource>
    <directory>${project.build.directory}/swagger-ui-2.1.1/dist</directory>
    </resource>
    </resources>
    </configuration>
    </execution>
    </executions>
    </plugin>
    </plugins>
    </build>
  9. @nosmokingpistol nosmokingpistol revised this gist Sep 14, 2015. 1 changed file with 8 additions and 6 deletions.
    14 changes: 8 additions & 6 deletions Swagger Setup for Embedded Jetty Server.md
    View file
    Original file line number Diff line number Diff line change
    @@ -3,9 +3,9 @@ In setting up a Jetty server with Jersey servlets, you may choose to use an embe

    In the Swagger Core setup, the current official recommendations involve an Application class, or a web.xml, neither of which are used in an embedded Jetty server setup. To add Swagger to your embedded Jetty Server, you must do 3 things:

    1. Add the package scanning packages to your servlets which will serve your REST API. {add-package-scanning}
    2. Add the Swagger package scanning servlet. {add-swagger-servlet}
    3. [Optional] Package the Swagger-UI static HTML5 content with your server {add-swagger-ui}
    1. [Add the package scanning packages to your servlets which will serve your REST API.](add-package-scanning)
    2. [Add the Swagger package scanning servlet.](add-swagger-servlet)
    3. [Package the Swagger-UI static HTML5 content with your server](add-swagger-ui)

    Let's start with a basic server class, adapted from the Eclipse tutorial above.

    @@ -37,7 +37,7 @@ In this example, the servlet serving the API is initialized as a ServletContaine

    ServletHolder apiServlet = context.addServlet(new MyServlet(), "/path/*");

    ## [Add the package scanning packages to your servlets which will serve your REST API.](add-package-scanning) ##
    ##Add the package scanning packages to your servlets which will serve your REST API## {add-package-scanning}
    First, to add the Swagger package scanning classes. Usually one would add them to the web.xml like [this](https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-Jersey-1.X-Project-Setup-1.5#package-scanning--concrete-class-selection). In your embedded Jetty servlet setup, you are setting the packages you are serving via the `"com.sun.jersey.config.property.packages"` property. So, add the `io.swagger.jaxrs.json;io.swagger.jaxrs.listing` packages to your servlet setup, like so:

    public class MyServer {
    @@ -56,7 +56,7 @@ First, to add the Swagger package scanning classes. Usually one would add them t
    server.join();
    }
    }

    ##Add the Swagger package scanning servlet## {add-swagger-servlet}
    Now, to configure and initialize Swagger. Based on [these](https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-Jersey-1.X-Project-Setup-1.5#configure-and-initialize-swagger) instructions, you'll now manually create and add the Swagger servlet. The path provided for the Swagger servlet is irrelevant, as it is not actually accessed through this path. **However, make sure it does not collide with any of your other resource paths!**

    public class MyServer {
    @@ -80,6 +80,8 @@ Now, to configure and initialize Swagger. Based on [these](https://github.com/sw
    }
    }

    Now, when you navigate to `http://<host>:<port>/api/swagger.json`, Swagger will generate a JSON response detailing your resource paths, their parameters, and their responses. However, most people prefer a more human readable method -- so we will now package the [Swagger-UI](https://github.com/swagger-api/swagger-ui) HTML5 project with your server.
    Now, when you navigate to `http://<host>:<port>/api/swagger.json`, Swagger will generate a JSON response detailing your resource paths, their parameters, and their responses.
    ##Package the Swagger-UI static HTML5 content with your server## {add-swagger-ui}
    However, most people prefer a more human readable method -- so we will now package the [Swagger-UI](https://github.com/swagger-api/swagger-ui) HTML5 project with your server.

    To your pom.xml, you need to add the ability to download and
  10. @nosmokingpistol nosmokingpistol revised this gist Sep 14, 2015. 1 changed file with 6 additions and 4 deletions.
    10 changes: 6 additions & 4 deletions Swagger Setup for Embedded Jetty Server.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,10 +1,11 @@
    # Swagger Setup for Embedded Jetty Server #
    In setting up a Jetty server with Jersey servlets, you may choose to use an embedded Jetty server setup. (See [here](https://wiki.eclipse.org/Jetty/Tutorial/Embedding_Jetty#Setting_a_ServletContext) for how to setup an embedded Jetty server). In this gist, we'll go through how to setup Swagger for this setup. I am using [Swagger 1.5](https://github.com/swagger-api/swagger-core/tree/v1.5.3), [Maven 3.3.3](https://maven.apache.org/download.cgi), [Jersey 1.8](https://jersey.java.net/download.html), and [Jetty 7.3](http://download.eclipse.org/jetty/). Make sure you add all dependencies to your pom.xml.

    In the Swagger Core setup, the current official recommendations involve an Application class, or a web.xml, neither of which are used in an embedded Jetty server setup. To add Swagger to your embedded Jetty Server, you must do 3 things:

    1. Add the package scanning packages to your servlets which will serve your REST API.
    2. Add the Swagger package scanning servlet.
    3. [Optional] Package the Swagger-UI static HTML5 content with your server
    1. Add the package scanning packages to your servlets which will serve your REST API. {add-package-scanning}
    2. Add the Swagger package scanning servlet. {add-swagger-servlet}
    3. [Optional] Package the Swagger-UI static HTML5 content with your server {add-swagger-ui}

    Let's start with a basic server class, adapted from the Eclipse tutorial above.

    @@ -35,7 +36,8 @@ Our package setup is very minimal:
    In this example, the servlet serving the API is initialized as a ServletContainer and has its values instantiated in-code. However, if you choose to make your own servlet class, then you will need to set parameters in that class instead, and you can then add a servlet like so:

    ServletHolder apiServlet = context.addServlet(new MyServlet(), "/path/*");


    ## [Add the package scanning packages to your servlets which will serve your REST API.](add-package-scanning) ##
    First, to add the Swagger package scanning classes. Usually one would add them to the web.xml like [this](https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-Jersey-1.X-Project-Setup-1.5#package-scanning--concrete-class-selection). In your embedded Jetty servlet setup, you are setting the packages you are serving via the `"com.sun.jersey.config.property.packages"` property. So, add the `io.swagger.jaxrs.json;io.swagger.jaxrs.listing` packages to your servlet setup, like so:

    public class MyServer {
  11. @nosmokingpistol nosmokingpistol revised this gist Sep 14, 2015. 1 changed file with 42 additions and 6 deletions.
    48 changes: 42 additions & 6 deletions Swagger Setup for Embedded Jetty Server.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,4 +1,4 @@
    In setting up a Jetty server with Jersey servlets, you may choose to use an embedded Jetty server setup. (See [here](https://wiki.eclipse.org/Jetty/Tutorial/Embedding_Jetty#Setting_a_ServletContext) for how to setup an embedded Jetty server). In this gist, we'll go through how to setup Swagger for this setup. I am using [Swagger 1.5](https://github.com/swagger-api/swagger-core/tree/v1.5.3), [Maven 3.3.3](https://maven.apache.org/download.cgi), [Jersey 1.8](https://jersey.java.net/download.html), and [Jetty 7.3](http://download.eclipse.org/jetty/).
    In setting up a Jetty server with Jersey servlets, you may choose to use an embedded Jetty server setup. (See [here](https://wiki.eclipse.org/Jetty/Tutorial/Embedding_Jetty#Setting_a_ServletContext) for how to setup an embedded Jetty server). In this gist, we'll go through how to setup Swagger for this setup. I am using [Swagger 1.5](https://github.com/swagger-api/swagger-core/tree/v1.5.3), [Maven 3.3.3](https://maven.apache.org/download.cgi), [Jersey 1.8](https://jersey.java.net/download.html), and [Jetty 7.3](http://download.eclipse.org/jetty/). Make sure you add all dependencies to your pom.xml.

    In the Swagger Core setup, the current official recommendations involve an Application class, or a web.xml, neither of which are used in an embedded Jetty server setup. To add Swagger to your embedded Jetty Server, you must do 3 things:

    @@ -15,21 +15,47 @@ Let's start with a basic server class, adapted from the Eclipse tutorial above.
    ServletContextHandler context = new ServletContextHandler(ServletContextHandler.SESSIONS);
    context.setContextPath("/");
    server.setHandler(context);
    ServletHolder apiServlet = context.addServlet(ServletContainer.class, "/api/*");
    apiServlet.setInitOrder(1);
    apiServlet.setInitParameter("com.sun.jersey.config.property.packages", "com.api.resources");
    server.start();
    server.join();
    }
    }

    In this example, the servlet serving the API is initialized as a ServletContainer and has its values instantiated in-code. However, if you choose to make your own servlet class, then you will need to set parameters in that class instead, and you can then add a servlet like:
    Our package setup is very minimal:
    - src
    - main
    - java
    - MyServer.java
    - resources

    In this example, the servlet serving the API is initialized as a ServletContainer and has its values instantiated in-code. However, if you choose to make your own servlet class, then you will need to set parameters in that class instead, and you can then add a servlet like so:

    ServletHolder apiServlet = context.addServlet(new MyServlet(), "/path/*");

    First, to add the Swagger package scanning classes. In your servlet setup, you are setting the packages you are serving via the `"com.sun.jersey.config.property.packages"` property. So, add the `io.swagger.jaxrs.json;io.swagger.jaxrs.listing` packages to your servlet setup, like so:
    First, to add the Swagger package scanning classes. Usually one would add them to the web.xml like [this](https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-Jersey-1.X-Project-Setup-1.5#package-scanning--concrete-class-selection). In your embedded Jetty servlet setup, you are setting the packages you are serving via the `"com.sun.jersey.config.property.packages"` property. So, add the `io.swagger.jaxrs.json;io.swagger.jaxrs.listing` packages to your servlet setup, like so:

    Let's start with a basic server class, adapted from the Eclipse tutorial above.
    public class MyServer {
    public static void main(String[] args) throws Exception
    {
    Server server = new Server(8080);
    ServletContextHandler context = new ServletContextHandler(ServletContextHandler.SESSIONS);
    context.setContextPath("/");
    server.setHandler(context);
    ServletHolder apiServlet = context.addServlet(ServletContainer.class, "/api/*");
    apiServlet.setInitOrder(1);
    apiServlet.setInitParameter("com.sun.jersey.config.property.packages", "com.api.resources;io.swagger.jaxrs.json;io.swagger.jaxrs.listing");
    server.start();
    server.join();
    }
    }

    Now, to configure and initialize Swagger. Based on [these](https://github.com/swagger-api/swagger-core/wiki/Swagger-Core-Jersey-1.X-Project-Setup-1.5#configure-and-initialize-swagger) instructions, you'll now manually create and add the Swagger servlet. The path provided for the Swagger servlet is irrelevant, as it is not actually accessed through this path. **However, make sure it does not collide with any of your other resource paths!**

    public class MyServer {
    public static void main(String[] args) throws Exception
    @@ -38,10 +64,20 @@ Let's start with a basic server class, adapted from the Eclipse tutorial above.
    ServletContextHandler context = new ServletContextHandler(ServletContextHandler.SESSIONS);
    context.setContextPath("/");
    server.setHandler(context);
    ServletHolder apiServlet = context.addServlet(ServletContainer.class, "/api/*");
    apiServlet.setInitOrder(1);
    **apiServlet.setInitParameter("com.sun.jersey.config.property.packages", "com.api.resources;io.swagger.jaxrs.json;io.swagger.jaxrs.listing");**
    apiServlet.setInitParameter("com.sun.jersey.config.property.packages", "com.api.resources;io.swagger.jaxrs.json;io.swagger.jaxrs.listing");
    ServletHolder swaggerServlet = context.addServlet(DefaultJaxrsConfig.class, "/swagger-core");
    swaggerServlet.setInitOrder(2);
    swaggerServlet.setInitParameter("api.version", "1.0.0");
    server.start();
    server.join();
    }
    }
    }

    Now, when you navigate to `http://<host>:<port>/api/swagger.json`, Swagger will generate a JSON response detailing your resource paths, their parameters, and their responses. However, most people prefer a more human readable method -- so we will now package the [Swagger-UI](https://github.com/swagger-api/swagger-ui) HTML5 project with your server.

    To your pom.xml, you need to add the ability to download and
  12. @nosmokingpistol nosmokingpistol revised this gist Sep 14, 2015. 1 changed file with 21 additions and 2 deletions.
    23 changes: 21 additions & 2 deletions Swagger Setup for Embedded Jetty Server.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,4 +1,4 @@
    In setting up a Jetty server with Jersey servlets, you may choose to use an embedded Jetty server setup. (See [here](https://wiki.eclipse.org/Jetty/Tutorial/Embedding_Jetty#Setting_a_ServletContext) for how to setup an embedded Jetty server). In this gist, we'll go through how to setup Swagger for this setup.
    In setting up a Jetty server with Jersey servlets, you may choose to use an embedded Jetty server setup. (See [here](https://wiki.eclipse.org/Jetty/Tutorial/Embedding_Jetty#Setting_a_ServletContext) for how to setup an embedded Jetty server). In this gist, we'll go through how to setup Swagger for this setup. I am using [Swagger 1.5](https://github.com/swagger-api/swagger-core/tree/v1.5.3), [Maven 3.3.3](https://maven.apache.org/download.cgi), [Jersey 1.8](https://jersey.java.net/download.html), and [Jetty 7.3](http://download.eclipse.org/jetty/).

    In the Swagger Core setup, the current official recommendations involve an Application class, or a web.xml, neither of which are used in an embedded Jetty server setup. To add Swagger to your embedded Jetty Server, you must do 3 things:

    @@ -25,4 +25,23 @@ Let's start with a basic server class, adapted from the Eclipse tutorial above.

    In this example, the servlet serving the API is initialized as a ServletContainer and has its values instantiated in-code. However, if you choose to make your own servlet class, then you will need to set parameters in that class instead, and you can then add a servlet like:

    ServletHolder apiServlet = context.addServlet(new MyServlet(), "/path/*");
    ServletHolder apiServlet = context.addServlet(new MyServlet(), "/path/*");

    First, to add the Swagger package scanning classes. In your servlet setup, you are setting the packages you are serving via the `"com.sun.jersey.config.property.packages"` property. So, add the `io.swagger.jaxrs.json;io.swagger.jaxrs.listing` packages to your servlet setup, like so:

    Let's start with a basic server class, adapted from the Eclipse tutorial above.

    public class MyServer {
    public static void main(String[] args) throws Exception
    {
    Server server = new Server(8080);
    ServletContextHandler context = new ServletContextHandler(ServletContextHandler.SESSIONS);
    context.setContextPath("/");
    server.setHandler(context);
    ServletHolder apiServlet = context.addServlet(ServletContainer.class, "/api/*");
    apiServlet.setInitOrder(1);
    **apiServlet.setInitParameter("com.sun.jersey.config.property.packages", "com.api.resources;io.swagger.jaxrs.json;io.swagger.jaxrs.listing");**
    server.start();
    server.join();
    }
    }
  13. @nosmokingpistol nosmokingpistol revised this gist Sep 14, 2015. 1 changed file with 13 additions and 16 deletions.
    29 changes: 13 additions & 16 deletions Swagger Setup for Embedded Jetty Server.md
    View file
    Original file line number Diff line number Diff line change
    @@ -8,23 +8,20 @@ In the Swagger Core setup, the current official recommendations involve an Appli

    Let's start with a basic server class, adapted from the Eclipse tutorial above.

    public class MyServer {
    public static void main(String[] args) throws Exception
    {
    Server server = new Server(8080);

    ServletContextHandler context = new ServletContextHandler(ServletContextHandler.SESSIONS);
    context.setContextPath("/");
    server.setHandler(context);

    ServletHolder apiServlet = context.addServlet(ServletContainer.class, "/api/*");
    apiServlet.setInitOrder(1);
    apiServlet.setInitParameter("com.sun.jersey.config.property.packages", "com.api.resources");

    server.start();
    server.join();
    public class MyServer {
    public static void main(String[] args) throws Exception
    {
    Server server = new Server(8080);
    ServletContextHandler context = new ServletContextHandler(ServletContextHandler.SESSIONS);
    context.setContextPath("/");
    server.setHandler(context);
    ServletHolder apiServlet = context.addServlet(ServletContainer.class, "/api/*");
    apiServlet.setInitOrder(1);
    apiServlet.setInitParameter("com.sun.jersey.config.property.packages", "com.api.resources");
    server.start();
    server.join();
    }
    }
    }

    In this example, the servlet serving the API is initialized as a ServletContainer and has its values instantiated in-code. However, if you choose to make your own servlet class, then you will need to set parameters in that class instead, and you can then add a servlet like:

  14. @nosmokingpistol nosmokingpistol revised this gist Sep 14, 2015. 1 changed file with 1 addition and 0 deletions.
    1 change: 1 addition & 0 deletions Swagger Setup for Embedded Jetty Server.md
    View file
    Original file line number Diff line number Diff line change
    @@ -27,4 +27,5 @@ Let's start with a basic server class, adapted from the Eclipse tutorial above.
    }

    In this example, the servlet serving the API is initialized as a ServletContainer and has its values instantiated in-code. However, if you choose to make your own servlet class, then you will need to set parameters in that class instead, and you can then add a servlet like:

    ServletHolder apiServlet = context.addServlet(new MyServlet(), "/path/*");
  15. @nosmokingpistol nosmokingpistol revised this gist Sep 14, 2015. 1 changed file with 1 addition and 1 deletion.
    2 changes: 1 addition & 1 deletion Swagger Setup for Embedded Jetty Server.md
    View file
    Original file line number Diff line number Diff line change
    @@ -27,4 +27,4 @@ Let's start with a basic server class, adapted from the Eclipse tutorial above.
    }

    In this example, the servlet serving the API is initialized as a ServletContainer and has its values instantiated in-code. However, if you choose to make your own servlet class, then you will need to set parameters in that class instead, and you can then add a servlet like:
    ServletHolder apiServlet = context.addServlet(new MyServlet(), "/path/*");
    ServletHolder apiServlet = context.addServlet(new MyServlet(), "/path/*");
  16. @nosmokingpistol nosmokingpistol revised this gist Sep 14, 2015. 1 changed file with 7 additions and 4 deletions.
    11 changes: 7 additions & 4 deletions Swagger Setup for Embedded Jetty Server.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,14 +1,14 @@
    In setting up a Jetty server with Jersey servlets, you may choose to use an embedded Jetty server setup. (See [here](https://wiki.eclipse.org/Jetty/Tutorial/Embedding_Jetty#Setting_a_ServletContext)). In this gist, we'll go through how to setup Swagger for this setup.
    In setting up a Jetty server with Jersey servlets, you may choose to use an embedded Jetty server setup. (See [here](https://wiki.eclipse.org/Jetty/Tutorial/Embedding_Jetty#Setting_a_ServletContext) for how to setup an embedded Jetty server). In this gist, we'll go through how to setup Swagger for this setup.

    In the Swagger Core setup, the only recommendations are involving a regular Application class, or a web.xml, neither of which are used in an embedded Jetty server setup. To add Swagger to your embedded Jetty Server, you must do 3 things:
    In the Swagger Core setup, the current official recommendations involve an Application class, or a web.xml, neither of which are used in an embedded Jetty server setup. To add Swagger to your embedded Jetty Server, you must do 3 things:

    1. Add the package scanning packages to your servlets which will serve your REST API.
    2. Add the Swagger package scanning servlet.
    3. [Optional] Package the Swagger-UI static HTML5 content with your server

    Let's start with a basic server class, adapted from the Eclipse tutorial above.

    public class OneServletContext {
    public class MyServer {
    public static void main(String[] args) throws Exception
    {
    Server server = new Server(8080);
    @@ -24,4 +24,7 @@ Let's start with a basic server class, adapted from the Eclipse tutorial above.
    server.start();
    server.join();
    }
    }
    }

    In this example, the servlet serving the API is initialized as a ServletContainer and has its values instantiated in-code. However, if you choose to make your own servlet class, then you will need to set parameters in that class instead, and you can then add a servlet like:
    ServletHolder apiServlet = context.addServlet(new MyServlet(), "/path/*");
  17. @nosmokingpistol nosmokingpistol revised this gist Sep 14, 2015. 1 changed file with 1 addition and 1 deletion.
    2 changes: 1 addition & 1 deletion Swagger Setup for Embedded Jetty Server.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,4 +1,4 @@
    In setting up a Jetty server with Jersey servlets, you may choose to use an embedded Jetty server setup. (See [https://wiki.eclipse.org/Jetty/Tutorial/Embedding_Jetty#Setting_a_ServletContext](here)). In this gist, we'll go through how to setup Swagger for this setup.
    In setting up a Jetty server with Jersey servlets, you may choose to use an embedded Jetty server setup. (See [here](https://wiki.eclipse.org/Jetty/Tutorial/Embedding_Jetty#Setting_a_ServletContext)). In this gist, we'll go through how to setup Swagger for this setup.

    In the Swagger Core setup, the only recommendations are involving a regular Application class, or a web.xml, neither of which are used in an embedded Jetty server setup. To add Swagger to your embedded Jetty Server, you must do 3 things:

  18. @nosmokingpistol nosmokingpistol revised this gist Sep 14, 2015. 1 changed file with 1 addition and 1 deletion.
    2 changes: 1 addition & 1 deletion Swagger Setup for Embedded Jetty Server.md
    View file
    Original file line number Diff line number Diff line change
    @@ -1,4 +1,4 @@
    In setting up a Jetty server with Jersey servlets, you may choose to use an embedded Jetty server setup. (See https://wiki.eclipse.org/Jetty/Tutorial/Embedding_Jetty#Setting_a_ServletContext). In this gist, we'll go through how to setup Swagger for this setup.
    In setting up a Jetty server with Jersey servlets, you may choose to use an embedded Jetty server setup. (See [https://wiki.eclipse.org/Jetty/Tutorial/Embedding_Jetty#Setting_a_ServletContext](here)). In this gist, we'll go through how to setup Swagger for this setup.

    In the Swagger Core setup, the only recommendations are involving a regular Application class, or a web.xml, neither of which are used in an embedded Jetty server setup. To add Swagger to your embedded Jetty Server, you must do 3 things:

  19. @nosmokingpistol nosmokingpistol renamed this gist Sep 14, 2015. 1 changed file with 0 additions and 0 deletions.
    0 Swagger Setup for Embedded Jetty Server → Swagger Setup for Embedded Jetty Server.md
    View file
    File renamed without changes.
  20. @nosmokingpistol nosmokingpistol created this gist Sep 14, 2015.
    27 changes: 27 additions & 0 deletions Swagger Setup for Embedded Jetty Server
    View file
    Original file line number Diff line number Diff line change
    @@ -0,0 +1,27 @@
    In setting up a Jetty server with Jersey servlets, you may choose to use an embedded Jetty server setup. (See https://wiki.eclipse.org/Jetty/Tutorial/Embedding_Jetty#Setting_a_ServletContext). In this gist, we'll go through how to setup Swagger for this setup.

    In the Swagger Core setup, the only recommendations are involving a regular Application class, or a web.xml, neither of which are used in an embedded Jetty server setup. To add Swagger to your embedded Jetty Server, you must do 3 things:

    1. Add the package scanning packages to your servlets which will serve your REST API.
    2. Add the Swagger package scanning servlet.
    3. [Optional] Package the Swagger-UI static HTML5 content with your server

    Let's start with a basic server class, adapted from the Eclipse tutorial above.

    public class OneServletContext {
    public static void main(String[] args) throws Exception
    {
    Server server = new Server(8080);

    ServletContextHandler context = new ServletContextHandler(ServletContextHandler.SESSIONS);
    context.setContextPath("/");
    server.setHandler(context);

    ServletHolder apiServlet = context.addServlet(ServletContainer.class, "/api/*");
    apiServlet.setInitOrder(1);
    apiServlet.setInitParameter("com.sun.jersey.config.property.packages", "com.api.resources");

    server.start();
    server.join();
    }
    }