The quick guide to API First development with JHipster

Many have written API’s and then genereated Swagger documentation based on the annotated code.

This is not what I am talking about. The idea is that you design the API you (your customer) will need, and describe it using Open API 3.0 Specification. Once your API is specified, you generate the interfaces and stubs to mock the endpoints and then implement them.

JHipster has provided a method for API-First development by integrating swagger-codegen into the project.

The quick version of the steps to API-First development with JHipster are:

1. Put your api.xml (Open API 3.0 spec) in src/main/resources/swagger/api.yml
2. Generate the sources with ./gradlew openApiGenerate(or just start the project)
3. Look at the code generated in ${buildDirectory}/generated-sources/openapi/src/main/java/${package}/web/api/
4. Implement @Service classes which implement the generate interfaces looking something like:

package com.my.api

...

@Service

public class MappingsApiImpl implements MappingsApiDelegate {

    public ResponseEntity<APIMappedEntity> getMappings(String mappingType) {
            ...
        return ResponseEntity.ok(apiMappedEntity);
    }
}

The apiMappedEntity Objects were also generated out of the OpenAPI specification of the response objects.

Once you generate the code, the APIs also show up in the JHipster generated Swagger Documentation.