Context

In no time we’ll see the whole world getting to adopt the code that’s been generated by AI/ML models for the requirements that we have in hand. At the moment, most of these applications are still in their nascent stages and the research is heading towards a direction where it will be complementing human software developers on writing code. Meanwhile, we should also equip ourselves to use the current available tools to move fast.

We, at TechConative thought we would be sharing our learnings with our community under the title Fast-track your software development, a blog series which can potentially save development, testing and deployment stages of software delivery.

While one side of the world is developing applications to generate the code based on the requirements, the other side still contemplates on development paradigms to choose with. For e.g. Should I choose Code-First or Design-First for my application. Number of blogs has been published in the past, and I assume this debate will go for a while and the opinion differs based on the scenario from which we’re coming.

Assume you have come to a conclusion and decided to go with Design-First approach and the next potential question that can hit your mind is “Is rapid development possible now?”. The answer to this your question is yes, and in fact you would have already guessed it from the title of this blog we’ll walk you through on how to fast-track your development by leveraging on OpenAPI code gen in this blog.

Assumptions

• You're starting with a design first approach.
• You're planning to launch your app with REST API and starting with designing of the API with OpenAPI spec(OAS). Stoplight typically helps us here on writing and validating the OAS.
• You're planning to develop your application in JVM based language with that is compatible with openapi-generator plugin.

Strategy

• We'll keep maintaining the OAS specification file(JSON or Yaml) as part of our code base and the openapi-generator plugin will make use of the specification file to generate the controller interfaces on every CI builds. (Active Code generator in the lingo of "The Pragmatic Programmer").
• The generated code containing the controller interface and the DTOs will be placed in target folder, so they are transient and not tracked as part of version control.
• The API controllers will be extending the generated interfaces, which will contain only the implementations and all the OpenAPI doc and the API spec will be available in the generated interface.

Approach

• Add your OAS specification file in your project(changes tracked with SCM).
• Add the plugin entry under build in the pom.xml (maven project),

        <build>
        <plugins>
            <plugin>
                <groupId>org.openapitools</groupId>
                <artifactId>openapi-generator-maven-plugin</artifactId>
                <!-- RELEASE_VERSION -->
                <version>5.4.0</version>
                <!-- /RELEASE_VERSION -->
                <executions>
                    <execution>
                        <goals>
                            <goal>generate</goal>
                        </goals>
                        <configuration>
                            <inputSpec>${project.basedir}/api/sample-api-generator-v1.yaml</inputSpec>
                            <generatorName>spring</generatorName>
                            <configOptions>
                                <apiPackage>com.techconative.openapispec.blog.api</apiPackage>
                                <modelPackage>com.techconative.openapispec.blog.model</modelPackage>
                                <serializableModel>true</serializableModel>
                                <snapshotVersion>true</snapshotVersion>
                                <interfaceOnly>true</interfaceOnly>
                                <skipDefaultInterface>true</skipDefaultInterface>
                                <useTags>true</useTags>
                            </configOptions>
                            <typeMappings>
                                <typeMapping>OffsetDateTime=Date</typeMapping>
                            </typeMappings>
                            <importMappings>
                                <importMapping>java.time.OffsetDateTime=java.util.Date</importMapping>
                            </importMappings>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
         </plugins>
        </build>

• Optionally, you can also have typeMapping that will help you to customize the type of object that you need to map in java.
• The code generation will automatically be taken care in compile phase, i.e. mvn clean compile will generate the code as configured.
• Now, You will have a source code generated inside the target directory, just write you controller class and extends the API generated using OpenAPI.

        @RestController
        public class UserRestController implements GithubApi{

        @Override public ResponseEntity<List<RepositoryVO>> getReposForUser(String userid) {

            // Your actual logic goes here
          return null;
        }

• The generated interface will contain annotations related to OAS documents and the same will be used for swagger page while running the application.
• With bootstrapped interface and DTO we're can roll our sleves for our logic implementation.

Example

You can find sample project here which generates a Class from OAS.

The produced API classes are located in the target folder as shown below.