Let's revisit the DepartmentResource class used in the previous sections. In this example, we will enhance the DepartmentResource class by adding the Swagger annotations discussed earlier. We use @Api to mark DepartmentResource as the Swagger resource. The @ApiOperation annotation describes the operation exposed by the DepartmentResource class:

import com.wordnik.swagger.annotations.Api; 
import com.wordnik.swagger.annotations.ApiOperation; 
import com.wordnik.swagger.annotations.ApiParam; 
import com.wordnik.swagger.annotations.ApiResponse; 
import com.wordnik.swagger.annotations.ApiResponses; 
//Other imports are removed for brevity 
 
@Stateless 
@Path("departments") 
@Api(value = "/departments", description = "Get departments 
     details") 
public class DepartmentResource  { 
 
    @ApiOperation(value = "Find department by id", 
        notes = "Specify a valid department id", 
        response = Department.class) 
    @ApiResponses(value = { 
        @ApiResponse(code = 400, message =  
        "Invalid department id supplied"), 
        @ApiResponse(code = 404, message = "Department not found") 
    }) 
    @GET 
    @Path("{id}") 
    @Produces("application/json") 
    public Department findDepartment( 
        @ApiParam(value = "The department id", required = true)  
        @PathParam("id") Integer id){ 
            return findDepartmentEntity(id); 
        } 
 
    //Rest of the codes are removed for brevity 
 
} 

To view the Swagger documentation, build the source and deploy it to the server. Once the application is deployed, you can navigate to http://<host>:<port>/<application-name>/<application-path>/swagger.json to view the Swagger resource listing in the JSON format. The Swagger URL for this example will look like the following:
http://localhost:8080/hrapp/webresource/swagger.json

The following sample Swagger representation is for the DepartmentResource class discussed in this section:

{ 
  "swagger": "2.0", 
  "info": { 
    "version": "1.0.0", 
    "title": "" 
  }, 
  "host": "localhost:8080", 
  "basePath": "/hrapp/webresources", 
  "tags": [ 
    { 
      "name": "user" 
    } 
  ], 
  "schemes": [ 
    "http" 
  ], 
  "paths": { 
    "/departments/{id}": { 
      "get": { 
        "tags": [ 
          "user" 
        ], 
        "summary": "Find department by id", 
        "description": "", 
        "operationId": "loginUser", 
        "produces": [ 
          "application/json" 
        ], 
        "parameters": [ 
          { 
            "name": "id", 
            "in": "path", 
            "description": "The department id", 
            "required": true, 
            "type": "integer", 
            "format": "int32" 
          } 
        ], 
        "responses": { 
          "200": { 
            "description": "successful operation", 
            "schema": { 
              "$ref": "#/definitions/Department" 
            } 
          }, 
          "400": { 
            "description": "Invalid department id supplied" 
          }, 
          "404": { 
            "description": "Department not found" 
          } 
        } 
      } 
    } 
  }, 
  "definitions": { 
    "Department": { 
      "properties": { 
        "departmentId": { 
          "type": "integer", 
          "format": "int32" 
        }, 
        "departmentName": { 
          "type": "string" 
        }, 
        "_persistence_shouldRefreshFetchGroup": { 
          "type": "boolean" 
        } 
      } 
    } 
  } 
} 

As mentioned at the beginning of this section, from the Swagger 2.0 release onward it supports the YAML representation of APIs. You can access the YAML representation by navigating to swagger.yaml. For instance, in the preceding example, the following URI gives you the YAML file:
http://<host>:<port>/<application-name>/<application-path>/swagger.yaml