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" } } }