[Contract-first-development] Tech talk on Swagger Code generation

Talk.md

1. Create directory - mkcdir barcampbangalore
2. Open swagger editor - https://editor.swagger.io/
3. Create Bookstore API Get Books
   • Author and/or Name Add Books Get Authors
   • Book name

openapi: 3.0.2
info:
 title: Book Store 
 description: 'My awesome bookstore. For more projects **check** [github](https://github.com/arvindkgs)'
 contact:
   email: [email protected]
 license:
   name: Apache 2.0
   url: http://www.apache.org/licenses/LICENSE-2.0.html
 version: 1.0.0
externalDocs:
 description: Find out more about Swagger
 url: http://swagger.io
servers:
- url: https://localhost:8080/
tags:
- name: book
- name: author
paths:
 /books:
   get:
     tags:
     - book
     summary: Get all books
     operationId: getBooks
     parameters: 
     - name: name
       schema:
         type: string
       in: query
     - name: author
       schema:
         type: string
       in: query
     responses:
       200:
         description: Get all books
         content: 
           application/json:
             schema:
               $ref: '#/components/schemas/Books'
   post:
     tags:
     - book
     summary: Add a new book to the store
     operationId: addBook
     requestBody:
       description: Book object that needs to be added to the store
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/Books'
       required: true
     responses:
       200:
         description: Added book
         content: 
           application/json:
             schema:
               $ref: '#/components/schemas/Book'
 /authors:
   get:
     tags:
     - author
     summary: Get all authors
     operationId: getAuthors
     parameters:
     - name: name
       schema:
         type: string
       in: query
     - name: book
       schema:
         type: string
       in: query
     responses:
       200:
         description: Get authors
         content:
           application/json:
             schema:
               type: array
               items:
                 type: string
components:
 schemas:
   Books:
     type: array
     items:
       $ref: '#/components/schemas/Book'
   Book:
     type: object
     properties:
       id:
         type: integer
         readOnly: true
       name:
         type: string
       genre:
         type: string
       isbn:
         type: string
       author:
         type: string
       purchase:
         type: string

4. Save yaml to 'barcampbangalore'
5. Download codegen jar - wget https://repo1.maven.org/maven2/io/swagger/codegen/v3/swagger-codegen-cli/3.0.25/swagger-codegen-cli-3.0.25.jar -O swagger-codegen-cli.jar
6. Create config.json -

{
  "hideGenerationTimestamp":true,
  "groupId":"com.barcamp.swagger",
  "artifactId":"swagger-demo",
  "artifactDescription":"Spring swagger demo server",
  "developerName":"arvind.kgs",
  "developerEmail":"[email protected]",
  "invokerPackage":"com.barcamp.swagger",
  "apiPackage":"com.barcamp.swagger.api",
  "modelPackage":"com.barcamp.swagger.dto",
  "configPackage": "com.barcamp.swagger.configuration",
  "interfaceOnly": true
}

5. Generate code - java -jar swagger-codegen-cli.jar generate -i bookstore.yaml -l spring -c config.json
6. Run - echo "pom.xml" >> .swagger-codegen-ignore
7. edit pom.xml - Add plugin

<plugin>
               <groupId>io.swagger.codegen.v3</groupId>
               <artifactId>swagger-codegen-maven-plugin</artifactId>
               <version>3.0.24</version>
               <executions>
                   <execution>
                       <goals>
                           <goal>generate</goal>
                       </goals>
                       <configuration>
                           <output>${project.basedir}</output>
                           <inputSpec>bookstore.yaml</inputSpec>
                           <language>spring</language>
                           <configurationFile>config.json</configurationFile>
                           <configOptions>
                               <sourceFolder>src/main/java</sourceFolder>
                           </configOptions>
                       </configuration>
                   </execution>
               </executions>
           </plugin>

8. Verify by visiting http://localhost:8080/swagger-ui/index.html
9. Create package 'com.barcamp.swagger.api.impl'
10. Move Controller files to 'impl'
11. Edit config.json - add "interfaceOnly": true
12. Edit pom.xml - add

 <dependency>
                       <groupId>org.springframework.boot</groupId>
                       <artifactId>spring-boot-starter-data-jpa</artifactId>
               </dependency>

               <dependency>
                       <groupId>com.h2database</groupId>
                       <artifactId>h2</artifactId>
                       <scope>runtime</scope>
               </dependency>
               <dependency>
                       <groupId>org.projectlombok</groupId>
                       <artifactId>lombok</artifactId>
                       <optional>true</optional>
               </dependency>

Replace spring-boot-maven-plugin with:

<plugin>
               <groupId>org.springframework.boot</groupId>
               <artifactId>spring-boot-maven-plugin</artifactId>
               <configuration>
                   <excludes>
                       <exclude>
                           <groupId>org.projectlombok</groupId>
                           <artifactId>lombok</artifactId>
                       </exclude>
                   </excludes>
               </configuration>
               <executions>
                   <execution>
                       <goals>
                           <goal>repackage</goal>
                       </goals>
                   </execution>
               </executions>
           </plugin>

13. mvn package
14. Add table.sql in src/main/resources

DROP TABLE IF EXISTS BOOKS;

CREATE TABLE BOOKS (
   id INT AUTO_INCREMENT PRIMARY KEY,
   name VARCHAR(250) NOT NULL,
   genre VARCHAR(50) NOT NULL,
   isbn INTEGER,
   author VARCHAR(250) NOT NULL,
   review VARCHAR(250)
);

INSERT INTO BOOKS VALUES('Dune', 'Sci-Fi', 9780736692403, 'Frank Herbert', 'https://www.goodreads.com/book/show/44767458-dune');

15. Create custom templates project, 15.1. mkcdir myTemplates 15.2. java -jar ~/Software/swagger-codegen-cli.jar meta -o . -n swagger -p com.barcamp.swagger.templates 15.3. mkcdir src/main/resources/handlebar/JavaSpring 15.4. Copy pojo.mustache https://github.com/swagger-api/swagger-codegen/blob/master/modules/swagger-codegen/src/main/resources/JavaSpring/api.mustache to current directory 15.5 mvn org.apache.maven.plugins:maven-install-plugin:2.5.2:install-file -Dfile=target/swagger-swagger-codegen-1.0.0.jar 15.5. Edit bookstore.yaml , 17.1 add below to Book: before type: object

x-java-class-annotation:
       - "@javax.persistence.Entity"

 17.2 Add below to id: after `type: integer`

x-java-field-annotation:
           - "@javax.persistence.Id"
           - "@javax.persistence.GeneratedValue(strategy = javax.persistence.GenerationType.IDENTITY)"

18. Edit pom.xml and add dependency

19. @javax.annotation.Generated(value = \"custom annotation\")