Lesson 1: Document the API with Swagger

1. Module 7 Overview

The goal of this module is to teach you about making an API fully Hypermedia enabled and evolving it once it goes into production (with minimal impact to clients).

Hypermedia and HATEOAS are foundational pieces of REST, and the tactics of API evolution are ultimately critical once the API starts to be used by third-party clients. This is what this module is focused on.


2. Goals

The relevant module you need to import when you're starting with this lesson is : m7-lesson1-start
If you want to skip and see the complete implementation, feel free to jump ahead and import: m7-lesson1


The goal of this lesson is to guide you through choosing the best way of documenting the API and then through a full Swagger setup within our Spring project implementation.

Everything should be fully documented with the nice Swagger UI by the end.


3. Lesson Notes

When deploying locally, here are the relevant URLs:

http://localhost:8082/um-webapp/api/roles

http://localhost:8082/um-webapp/api/swagger-resources

http://localhost:8082/um-webapp/api/v2/api-docs

http://localhost:8082/um-webapp/api/swagger-ui.html


Note that in the code of this module, we're introducing a new technology - JPA Metamodels. These are, simply put - helper classes that we can use alongside our entities, with JPA Criteria, to write queries easier.


4. Resources

- Swagger

- the Springfox project

- the Springfox project documentation

RwS - Document the API with Swagger - transcript.pdf
Complete and Continue