Spring Boot Bootcamp – Workbooks and Challenges
)}

Challenge

Documentation helps the consumer understand how to use your API.

Launch the Starter Project

Screen Shot 2022-08-11 at 11.15.03 PM.png

OpenAPI

OpenAPI is a standard format that defines the capabilities of a REST API.

Below is a snippet from an OpenAPI specification that describes:

  1. The path for one of the operations, as well as a description of what it does.
  2. Parameters to be included for the operation to succeed.
  3. The response to expect if the client makes a good request.

Screen Shot 2022-08-11 at 11.40.25 PM.png

Computers can read the OpenAPI spec and generate human-friendly documentation.

Screen Shot 2022-08-11 at 11.53.23 PM.png

In turn, consumers can read the documentation and learn how to use your API.

Purpose of this Challenge

In this challenge, you will generate documentation for the Contact API.

Dependencies

The starter project includes the OpenAPI dependency.

Screen Shot 2022-08-11 at 11.55.32 PM.png

Side Note

If you remove the version, Maven will not know which version of your dependency to grab:

Screen Shot 2022-08-12 at 12.00.06 AM.png

Conversely, the parent POM (Spring Boot Starter Parent) takes care of dependency management for Spring Boot starters.

Screen Shot 2022-08-12 at 12.11.18 AM.png

Task 1

Run the application, and navigate to http://localhost:8080/v3/api-docs.

Screen Shot 2022-08-12 at 4.41.28 PM.png

An OpenAPI spec that documents your application is autogenerated. If you format the JSON, notice that it detects and documents every operation:

Screen Shot 2022-08-12 at 4.54.15 PM.png

Navigate to http://localhost:8080/swagger-ui/index.html.

Screen Shot 2022-08-12 at 4.58.44 PM.png

Task 2

The next task is to configure the OpenAPI definition:

  • Create a new folder called config.
  • Create a new class called OpenApiConfig.
  • Mark this class as a source of bean definitions (hint: see cheat sheet from the beans section).
  • Create a bean definition named: openAPI that returns an OpenAPI object.

Task 3

Behind the scenes, Spring Boot can leverage the OpenAPI bean to update the:

  1. Title.
  2. Version.
  3. Description of what the API does.

Screen Shot 2022-08-12 at 5.11.46 PM.png

Consult the Spring Documentation, and scroll down until it discusses the OpenAPI bean. Take inspiration from the docs, and configure your OpenAPI bean to achieve the following output:

Screen Shot 2022-08-12 at 5.16.32 PM.png

Task 4

@Tag can group operations together.

If you look inside the current OpenAPI definition, every operation has a contact-controller tag.

Screen Shot 2022-08-12 at 6.39.38 PM.png

As a result, Swagger groups the operations under the same tag.

Screen Shot 2022-08-12 at 6.42.21 PM.png

Your next exercise is to apply the @Tag(name = "name") annotation to each operation.

Screen Shot 2022-08-12 at 6.45.30 PM.png

Task 5

@Tag can be applied at the class or method level.

Given that @Tag has attributes of name and description:

  • Group every operation under the tag: Contact Controller.
  • Provide a general description of: "Create and retrieve contacts".

Screen Shot 2022-08-12 at 6.52.49 PM.png

Task 6

Use @Operation at the method level to provide each operation with a summary and description.

Screen Shot 2022-08-12 at 6.54.39 PM.png

getContacts

  • summary: Retrieves contacts
  • description: Provides a list of all contacts

getContact

  • summary: Get contact by Id
  • description: Returns a contact based on an ID

createContact

  • summary: Create Contact
  • description: Creates a contact from the provided payload

Task 7

@ApiResponse documents how each operation responds.

Apply it at the level of each method:

getContacts


import io.swagger.v3.oas.annotations.media.*; import io.swagger.v3.oas.annotations.responses.ApiResponse; @ApiResponse(responseCode = "200", description = "Successful retrieval of contacts", content = @Content(array = @ArraySchema(schema = @Schema(implementation = Contact.class))))

This reads like english. The operation will:

  1. Return a status code of 200.
  2. Retrieve all contacts from the datastore.
  3. Return a JSON Array of Contact resources.

Screen Shot 2022-08-12 at 7.53.00 PM.png

getContact


@ApiResponses(value = {
    @ApiResponse(responseCode = "404", description = "Contact doesn't exist", content = @Content(schema = @Schema(implementation = ErrorResponse.class))),
    @ApiResponse(responseCode = "200", description = "Successful retrieval of contact", content = @Content(schema = @Schema(implementation = Contact.class))),
})

Since getContact is also prone to a 404 response, it must be documented to the consumer as well

createContact


@ApiResponses(value = {
    @ApiResponse(responseCode = "201", description = "Successful creation of contact"),
    @ApiResponse(responseCode = "400", description = "Bad request: unsuccessful submission", content = @Content(schema = @Schema(implementation = ErrorResponse.class)))
 })

Task 8

Add the following attribute to each @RequestMapping:

  • @GetMapping(value = "/contact/all", produces = MediaType.APPLICATION_JSON_VALUE)

This will specify that the operation produces a JSON.

Screen Shot 2022-08-12 at 7.58.33 PM.png

Final Remarks

Congratulations! You just documented your API. Consumers can use it to understand how it works.

Feedback Summary
5.0
3 students
5

100%
4

0%
3

0%
2

0%
1

0%
Written Reviews
There are no written reviews yet.