[JavaEE] Create API documents with Swagger

We mainly need to modify our Model and REST endpoint code to enable swagger Document.

model/Book.java: By doing this, we can get each model defination in swagger

rest/BookRespostory.java: By doing this, we can get each endpoint of API

BoodEndpoint.java:

package com.pluralsight.bookstore.rest;

import com.pluralsight.bookstore.model.Book;
import com.pluralsight.bookstore.repository.BookRepository;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import io.swagger.annotations.ApiResponse;
import io.swagger.annotations.ApiResponses;

import javax.inject.Inject;
import javax.validation.constraints.Min;
import javax.ws.rs.*;
import javax.ws.rs.core.Context;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.UriInfo;
import java.net.URI;
import java.util.List;

import static javax.ws.rs.core.MediaType.APPLICATION_JSON;
import static javax.ws.rs.core.MediaType.TEXT_PLAIN;

@Path("/books")
@Api("Book")
public class BookEndpoint {

    // ======================================
    // =          Injection Points          =
    // ======================================

    @Inject
    private BookRepository bookRepository;

    // ======================================
    // =          Business methods          =
    // ======================================

    @POST
    @Consumes(APPLICATION_JSON)
    @ApiOperation(value = "Create a book given a Json Book reforestation")
    @ApiResponses({
            @ApiResponse(code = 201, message = "The book was created"),
            @ApiResponse(code = 415, message = "Format error")
    })
    public Response createBook(Book book, @Context UriInfo uriInfo) {
        book = bookRepository.create(book);
        URI createdURI = uriInfo.getBaseUriBuilder().path(book.getId().toString()).build();
        return Response.created(createdURI).build();
    }

    @GET
    @Path("/{id : \\d+}")
    @Produces(APPLICATION_JSON)
    @ApiOperation(value = "Returns a book given an id", response = Book.class)
    @ApiResponses({
            @ApiResponse(code = 200, message = "Book found"),
            @ApiResponse(code = 404, message = "Book not found")
    })
    public Response getBook(@PathParam("id") @Min(1) Long id) {
        Book book = bookRepository.find(id);

        if (book == null)
            return Response.status(Response.Status.NOT_FOUND).build();

        return Response.ok(book).build();
    }

    @DELETE
    @Path("/{id : \\d+}")
    @ApiOperation(value = "Delete a book given an id")
    @ApiResponses({
            @ApiResponse(code = 204, message = "Book has been deleted"),
            @ApiResponse(code = 400, message = "Invalid param id"),
            @ApiResponse(code = 500, message = "Book not exists")
    })
    public Response deleteBook(@PathParam("id") @Min(1) Long id) {
        bookRepository.delete(id);
        return Response.noContent().build();
    }

}

model/Book.java:

package com.pluralsight.bookstore.model;

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;

import javax.persistence.*;
import javax.validation.constraints.Min;
import javax.validation.constraints.NotNull;
import javax.validation.constraints.Past;
import javax.validation.constraints.Size;
import java.util.Date;

/**
 * @author Antonio Goncalves
 *         http://www.antoniogoncalves.org
 *         --
 */

@Entity
@ApiModel(description = "Book resource representation")
public class Book {

    // ======================================
    // =             Attributes             =
    // ======================================

    @Id
    @GeneratedValue
    @ApiModelProperty("Identifier")
    private Long id;

    @Column(length = 200)
    @NotNull
    @Size(min = 1, max = 200)
    @ApiModelProperty("Title of the book")
    private String title;

    @Column(length = 10000)
    @Size(min = 1, max = 10000)
    @ApiModelProperty("Description of the book")
    private String description;

    // ======================================
    // =            Constructors            =
    // ======================================

    public Book() {
    }

    public Book(String isbn, String title, Float unitCost, Integer nbOfPages, com.pluralsight.bookstore.model.Language language, Date publicationDate, String imageURL, String description) {
        this.isbn = isbn;
        this.title = title;
        this.unitCost = unitCost;
        this.nbOfPages = nbOfPages;
        this.language = language;
        this.publicationDate = publicationDate;
        this.imageURL = imageURL;
        this.description = description;
    }

}

In the end, the Swagger.json looks like this:

{
  "swagger" : "2.0",
  "info" : {
    "description" : "BookStore APIs exposed from a Java EE back-end to an Angular front-end",
    "version" : "1.0.0",
    "title" : "BookStore APIs",
    "contact" : {
      "name" : "Antonio Goncalves",
      "url" : "https://app.pluralsight.com/library/search?q=Antonio+Goncalves",
      "email" : "antonio.goncalves@gmail.com"
    }
  },
  "host" : "localhost:8080",
  "basePath" : "/bookstore-back/api",
  "tags" : [ {
    "name" : "Book"
  } ],
  "schemes" : [ "http", "https" ],
  "paths" : {
    "/books" : {
      "get" : {
        "tags" : [ "Book" ],
        "summary" : "Returns all the books",
        "description" : "",
        "operationId" : "getBooks",
        "produces" : [ "application/json" ],
        "responses" : {
          "200" : {
            "description" : "Books found",
            "schema" : {
              "type" : "array",
              "items" : {
                "$ref" : "#/definitions/Book"
              }
            }
          },
          "204" : {
            "description" : "No books found"
          }
        }
      },
      "post" : {
        "tags" : [ "Book" ],
        "summary" : "Creates a book given a JSon Book representation",
        "description" : "",
        "operationId" : "createBook",
        "consumes" : [ "application/json" ],
        "parameters" : [ {
          "in" : "body",
          "name" : "body",
          "description" : "Book to be created",
          "required" : true,
          "schema" : {
            "$ref" : "#/definitions/Book"
          }
        } ],
        "responses" : {
          "201" : {
            "description" : "The book is created"
          },
          "415" : {
            "description" : "Format is not JSon"
          }
        }
      }
    },
    "/books/count" : {
      "get" : {
        "tags" : [ "Book" ],
        "summary" : "Returns the number of books",
        "description" : "",
        "operationId" : "countBooks",
        "produces" : [ "text/plain" ],
        "responses" : {
          "200" : {
            "description" : "Number of books found",
            "schema" : {
              "type" : "integer",
              "format" : "int64"
            }
          },
          "204" : {
            "description" : "No books found"
          }
        }
      }
    },
    "/books/{id}" : {
      "get" : {
        "tags" : [ "Book" ],
        "summary" : "Returns a book given an id",
        "description" : "",
        "operationId" : "getBook",
        "produces" : [ "application/json" ],
        "parameters" : [ {
          "name" : "id",
          "in" : "path",
          "required" : true,
          "type" : "integer",
          "minimum" : 1.0,
          "pattern" : "\\d+",
          "format" : "int64"
        } ],
        "responses" : {
          "200" : {
            "description" : "Book found",
            "schema" : {
              "$ref" : "#/definitions/Book"
            }
          },
          "400" : {
            "description" : "Invalid input. Id cannot be lower than 1"
          },
          "404" : {
            "description" : "Book not found"
          }
        }
      },
      "delete" : {
        "tags" : [ "Book" ],
        "summary" : "Deletes a book given an id",
        "description" : "",
        "operationId" : "deleteBook",
        "parameters" : [ {
          "name" : "id",
          "in" : "path",
          "required" : true,
          "type" : "integer",
          "minimum" : 1.0,
          "pattern" : "\\d+",
          "format" : "int64"
        } ],
        "responses" : {
          "204" : {
            "description" : "Book has been deleted"
          },
          "400" : {
            "description" : "Invalid input. Id cannot be lower than 1"
          },
          "500" : {
            "description" : "Book not found"
          }
        }
      }
    }
  },
  "definitions" : {
    "Book" : {
      "type" : "object",
      "required" : [ "isbn", "title" ],
      "properties" : {
        "id" : {
          "type" : "integer",
          "format" : "int64",
          "description" : "Identifier"
        },
        "title" : {
          "type" : "string",
          "description" : "Title of the book",
          "minLength" : 1,
          "maxLength" : 200
        },
        "description" : {
          "type" : "string",
          "description" : "Summary describing the book",
          "minLength" : 1,
          "maxLength" : 10000
        },
        "unitCost" : {
          "type" : "number",
          "format" : "float",
          "description" : "Unit cost",
          "minimum" : 1.0
        },
        "isbn" : {
          "type" : "string",
          "description" : "ISBN number",
          "minLength" : 1,
          "maxLength" : 50
        },
        "publicationDate" : {
          "type" : "string",
          "format" : "date-time",
          "description" : "Date in which the book has been published"
        },
        "nbOfPages" : {
          "type" : "integer",
          "format" : "int32",
          "description" : "Number of pages"
        },
        "imageURL" : {
          "type" : "string",
          "description" : "URL of the image cover"
        },
        "language" : {
          "type" : "string",
          "description" : "Language in which the book has been written",
          "enum" : [ "ENGLISH", "FRENCH", "SPANISH", "PORTUGUESE", "ITALIAN", "FINISH", "GERMAN", "DEUTSCH", "RUSSIAN" ]
        }
      },
      "description" : "Book resource representation"
    }
  }
}