Lesson 7 - Documentation

Of course, documentation makes or breaks your api - without it who is going to use it, who is going to be able to use it?  Writing documentation is tedious, but very important.
Fortunately, there is a specification called OpenApi, formerly known as the Swagger Specification, which lets you describe your API using JSON or YAML which other tools can then import in order to generate code or display it as interactive API documentation.

The Springfox library enables this dynamically-generated documentation by letting the code auto-describe itself.
This simply means adding a simple configuration to your project:

Something like :
@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket api() {
        return new Docket(DocumentationType. SWAGGER_2)
                . select()
                . apis(RequestHandlerSelectors. any())
                . paths(PathSelectors. any())
                . build()
                . apiInfo(apiInfo());
    }

Then Springfox will read the annotations decorating your methods and classes such as @PostMapping, @GetMapping, etc in order to automatically generate the documentation on how to call them, what type of parameters to use etc.

There was a Springfox bug, which I'm glad to say that I've played a major role in fixing. It is described in the Github issue: 
@ExampleProperty/value is getting ignored #3037

to which I offered a solution, which ultimately lead to a fix that was incorporated in the library's latest version.

At this point, reflecting back, we've gone a long way. We can now build REST APIs, GraphQL APIs, Microservices and document them. So what's left? Testing.

Lesson 8 - Unit & Integration Tests

The JUnit, Mockito and MockMVC suites cover the full spectrum of testing, both unit and integration. JUnit is a popular unit testing framework that allows you to test individual units of source code, while Mockito is a mocking framework which provides data for the JUnit tests. Using annotations once again, @WebMvcTest for Unit and @SpringBootTest for Integration testing.

Project - Vehicles API

Finally, the project. It's is multi-module project that combines everything learnt thus far. It requires writing a Vehicles REST API which in turn calls two other APIs by means of RestTemplate or WebClient which are registered with Eureka. In the end we unit- and integration-test it.

Each Module corresponds to a distinct API: 

• Pricing-service (to provide price of the car)
• Boogle-maps (to provide location of the car)
• Vehicle-api (The main module that provide API to combine details of the car and return the details in response) 

The idea is that each time a user requests car detail from the Vehicle API, the details of price and location are fetched from pricing-service and boogle-maps respectively.

A big help was that the boilerplate of the project was in place so we could get started right away with implementing the business logic. The project also made use of HATEOAS to represent the details of each car instance hierarchically.

Summary

To sum up, "Web Services and APIs" was a chapter that provided a holistic overview to make for a well-rounded developer. The material was introductory, but succinct. There's much more to be discovered once you start getting more involved. However, the solid foundation has been set. I especially liked the demystifying of Microservices part.

Next stop is "Data Stores and Persistence".

More Information

Java Web Developer Nanodegree

Related Articles

The Insider's Guide to the Java Web Developer Nanodegree - 1

The Insider's Guide to the Java Web Developer Nanodegree - 2

To be informed about new articles on I Programmer, sign up for our weekly newsletter, subscribe to the RSS feed and follow us on Twitter, Facebook or Linkedin.

Comments

Make a Comment or View Existing Comments Using Disqus

or email your comment to: comments@i-programmer.info