- \n
- Create a maven project and configure “
openapi-generator-maven-plugin<\/code>“.<\/li>\n- Create an OpenAPI specification –
products.yaml<\/code>.<\/li>\n- Execute the maven
generate-source<\/code> command to generate source code from theproducts.yaml<\/code> file.<\/li>\n- Create an implementation class for the generated interface.<\/li>\n
- Create Junit tests.<\/li>\n
- Update the
products.yaml<\/code> file with the “x-spring-cacheable<\/code>” vendor-specific extension with the default setting.<\/li>\n- Update the
products.yaml<\/code> file with the “x-spring-cacheable<\/code>” vendor-specific extension and set the cache name.<\/li>\n- Re-generate the source code with the built-in template and test with Junit tests.<\/li>\n
- Re-generate the source code with a custom template and test with Junit tests.<\/li>\n<\/ul>\n
<\/a>2. Setup Maven Project for OpenAPI Generator<\/h2>\n
OpenAPI generator supports a wide variety of generators<\/a>. In this example, I will add “
openapi-generator-maven-plugin<\/code>” in thepom.xml<\/code> file and generate code based on theproducts.yaml<\/code> file via the “spring<\/code>” generator.<\/p>\npom.xml<\/em><\/span><\/p>\n
<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<project xmlns=\"http:\/\/maven.apache.org\/POM\/4.0.0\"\n\txmlns:xsi=\"http:\/\/www.w3.org\/2001\/XMLSchema-instance\"\n\txsi:schemaLocation=\"http:\/\/maven.apache.org\/POM\/4.0.0 http:\/\/maven.apache.org\/xsd\/maven-4.0.0.xsd\">\n\t<modelVersion>4.0.0<\/modelVersion>\n\t<artifactId>spring-boot-openapi<\/artifactId>\n\t<name>spring-boot-openapi<\/name>\n\t<packaging>jar<\/packaging>\n\t<description>OpenAPI Generator module<\/description>\n\n\t<parent>\n\t\t<groupId>org.springframework.boot<\/groupId>\n\t\t<artifactId>spring-boot-starter-parent<\/artifactId>\n\t\t<version>3.2.5<\/version>\n\t\t<relativePath \/>\n\t<\/parent>\n\n\t<dependencies>\n\t\t<dependency>\n\t\t\t<groupId>org.springframework.boot<\/groupId>\n\t\t\t<artifactId>spring-boot-starter-web<\/artifactId>\n\t\t<\/dependency>\n\t\t<dependency>\n\t\t\t<groupId>org.springframework.boot<\/groupId>\n\t\t\t<artifactId>spring-boot-starter-test<\/artifactId>\n\t\t\t<scope>test<\/scope>\n\t\t<\/dependency>\n\t\t<dependency>\n\t\t\t<groupId>org.springframework.boot<\/groupId>\n\t\t\t<artifactId>spring-boot-starter-validation<\/artifactId>\n\t\t<\/dependency>\n\t\t<dependency>\n\t\t\t<groupId>jakarta.validation<\/groupId>\n\t\t\t<artifactId>jakarta.validation-api<\/artifactId>\n\t\t<\/dependency>\n\n\t\t<dependency>\n\t\t\t<groupId>javax.annotation<\/groupId>\n\t\t\t<artifactId>javax.annotation-api<\/artifactId>\n\t\t\t<version>1.3.2<\/version>\n\t\t<\/dependency>\n\t\t<dependency>\n\t\t\t<groupId>io.swagger.core.v3<\/groupId>\n\t\t\t<artifactId>swagger-annotations<\/artifactId>\n\t\t\t<version>2.2.20<\/version>\n\t\t<\/dependency>\n\n\t<\/dependencies>\n\n\t<build>\n\t\t<plugins>\n\t\t\t<plugin>\n\t\t\t\t<groupId>org.openapitools<\/groupId>\n\t\t\t\t<artifactId>openapi-generator-maven-plugin<\/artifactId>\n\t\t\t\t<version>7.5.0<\/version>\n\t\t\t\t<executions>\n\t\t\t\t\t<execution>\n\t\t\t\t\t\t<goals>\n\t\t\t\t\t\t\t<goal>generate<\/goal>\n\t\t\t\t\t\t<\/goals>\n\t\t\t\t\t\t<configuration>\n\t\t\t\t\t\t\t<inputSpec>\n\t\t\t\t\t\t\t\t${project.basedir}\/src\/main\/resources\/api\/products.yaml<\/inputSpec>\n\t\t\t\t\t\t\t<generatorName>spring<\/generatorName>\n\t\t\t\t\t\t\t<supportingFilesToGenerate>ApiUtil.java<\/supportingFilesToGenerate>\n\t\t\t\t\t\t<!--\t<templateResourcePath>\n\t\t\t\t\t\t\t\t${project.basedir}\/src\/main\/resources\/templates\/JavaSpring\n\t\t\t\t\t\t\t<\/templateResourcePath>-->\n\t\t\t\t\t\t\t<globalProperties>\n\t\t\t\t\t\t\t\t<debugOpenAPI>true<\/debugOpenAPI>\n\t\t\t\t\t\t\t<\/globalProperties>\n\t\t\t\t\t\t\t<configOptions>\n\t\t\t\t\t\t\t\t<delegatePattern>true<\/delegatePattern>\n\t\t\t\t\t\t\t\t<apiPackage>com.zheng.demo.openapi.products.api<\/apiPackage>\n\t\t\t\t\t\t\t\t<modelPackage>\n\t\t\t\t\t\t\t\t\tcom.zheng.demo.openapi.products.api.model<\/modelPackage>\n\t\t\t\t\t\t\t\t<documentationProvider>source<\/documentationProvider>\n\t\t\t\t\t\t\t\t<dateLibrary>java8<\/dateLibrary>\n\t\t\t\t\t\t\t\t<openApiNullable>false<\/openApiNullable>\n\t\t\t\t\t\t\t\t<useJakartaEe>true<\/useJakartaEe>\n\t\t\t\t\t\t\t\t<useSpringBoot3>true<\/useSpringBoot3>\n\t\t\t\t\t\t\t<\/configOptions>\n\t\t\t\t\t\t<\/configuration>\n\t\t\t\t\t<\/execution>\n\t\t\t\t<\/executions>\n\t\t\t<\/plugin>\n\t\t\t<plugin>\n\t\t\t\t<groupId>org.springframework.boot<\/groupId>\n\t\t\t\t<artifactId>spring-boot-maven-plugin<\/artifactId>\n\t\t\t<\/plugin>\n\t\t<\/plugins>\n\t<\/build>\n\n\t<properties>\n\t\t<maven.compiler.source>17<\/maven.compiler.source>\n\t\t<maven.compiler.target>17<\/maven.compiler.target>\n\t<\/properties>\n\n<\/project><\/pre>\n- \n
- line 54: add the
openapi-generator-maven-plugin<\/code> plugin.<\/li>\n- line 63: config the
inputSpec<\/code> with the products.yaml.<\/li>\n- line 64, use the “
spring<\/code>” generator.<\/li>\n- line 73: set
delegatePattern<\/code> totrue<\/code>.<\/li>\n- line 74: name
apiPackage<\/code> tocom.zheng.demo.openapi.products.api<\/code>.<\/li>\n- line 75: name
modelPackage<\/code> tocom.zheng.demo.openapi.products.api.model<\/code>.<\/li>\n- line 80: set
useJakartaEe<\/code> totrue<\/code> to use the Jakarta validation.<\/li>\n- line 81: set
useSpringBoot3<\/code> totrue<\/code>.<\/li>\n<\/ul>\nLaunch swagger editor<\/a> at any browser and create a simple RestFul API specification to create and get a product. Save the specification in the
products.yaml<\/code> file. <\/p>\nHere is the screenshot of products API.<\/p>\n
\n![\"\"](\"https:\/\/www.javacodegeeks.com\/wp-content\/uploads\/2024\/05\/swaggeruiAPI.jpg\")
<\/a>Figure 1. Product APIs<\/figcaption><\/figure>\n<\/div>\n Here is the product API’s YAML specification.<\/p>\n
products.yaml<\/em><\/span><\/p>\n
openapi: 3.0.0\ninfo:\n title: Product API\n version: 1.0.0\nservers:\n - description: Test server\n url: http:\/\/localhost:8080\npaths:\n \/products\/{id}:\n get:\n tags:\n - products\n summary: Get product detail for a given product id\n operationId: getProduct\n security:\n - ApiKey:\n - Product.Read\n parameters:\n - name: id\n in: path\n required: true\n description: Product's identifier\n schema:\n type: number\n \n responses:\n '200':\n description: OK\n content:\n application\/json:\n schema:\n $ref: '#\/components\/schemas\/ProductDO'\n \/products: \n post:\n tags:\n - products\n summary: Create a product\n operationId: createProduct\n requestBody:\n description: Create a new prodcut in the store\n content:\n application\/json:\n schema:\n $ref: '#\/components\/schemas\/ProductDO'\n required: true\n security:\n - ApiKey:\n - Product.Create\n responses:\n '200':\n description: OK\n content:\n application\/json:\n schema:\n $ref: '#\/components\/schemas\/ProductDO'\ncomponents:\n securitySchemes:\n ApiKey:\n type: apiKey\n in: header\n name: X-API-KEY\n schemas:\n ProductDO:\n description: Product Information\n type: object\n properties:\n id:\n type: number\n description: product id\n name:\n type: string\n description: product name\n price:\n type: number\n description: product price value<\/pre>\nCopy the
products.yaml<\/code> file and create two versions so there are 3 files underresources\\api folder<\/code>:<\/p>\napi folder<\/em><\/span><\/p>\n
C:\\MaryTools\\workspace\\JCG\\spring-boot-openapi\\src\\main\\resources\\api>dir\n Volume in drive C is OS\n Volume Serial Number is 92BA-6AB7\n\n Directory of C:\\MaryTools\\workspace\\JCG\\spring-boot-openapi\\src\\main\\resources\\api\n\n05\/04\/2024 07:56 PM .\n05\/03\/2024 09:13 PM ..\n05\/04\/2024 07:55 PM 1,734 products.yaml\n05\/04\/2024 07:40 PM 1,765 products1.yaml\n05\/04\/2024 08:59 AM 1,786 products2.yaml\n 3 File(s) 5,285 bytes\n 2 Dir(s) 109,910,233,088 bytes free\n\nC:\\MaryTools\\workspace\\JCG\\spring-boot-openapi\\src\\main\\resources\\api><\/pre>\n
- \n
- The
products.yaml<\/code> has no vendor-specific extension, therefore can be generated without any customization.<\/li>\n- The
products1.yaml<\/code> file has a vendor-spec extension and sets thex-spring-cacheable<\/code> astrue<\/code>.<\/li>\n- The
products2.yaml<\/code> file sets thex-spring-cacheable<\/code> with the defined cache name.<\/li>\n<\/ul>\nThe difference between
products1.yaml<\/code> andproducts2.yaml<\/code> is showing in the following screenshot:<\/p>\n\n![\"\"](\"https:\/\/www.javacodegeeks.com\/wp-content\/uploads\/2024\/05\/admin.jpg\")
<\/a>Figure 2. Products.yaml x-spring-cacheable Difference<\/figcaption><\/figure>\n<\/div>\n 3. API Implementation<\/h2>\n
In this step, I will generate a spring boot server stub with the “
spring<\/code>” generator via its built-in template and create the implementation class and test the generated code with Junit tests.<\/p>\n3.1 Create Spring Boot Application<\/h3>\n
Create a spring boot application and annotate with both
@SpringBootApplication<\/code> and@EnableCaching<\/code>.<\/p>\nProductApplication.java<\/em><\/span><\/p>\n
package com.zheng.demo.openapi.products;\n\nimport org.springframework.boot.SpringApplication;\nimport org.springframework.boot.autoconfigure.SpringBootApplication;\nimport org.springframework.cache.annotation.EnableCaching;\n\n@SpringBootApplication\n@EnableCaching\npublic class ProductsApplication {\n\n public static void main(String[] args) {\n SpringApplication.run(ProductsApplication.class, args);\n }\n}\n<\/pre>\n3.2 Create Implementation Classes<\/h3>\n
In this step, I will create an implementation class for the generated interface with mocked data.<\/p>\n
ProductsApiImpl.java<\/em><\/span><\/p>\n
package com.zheng.demo.openapi.products.service;\n\nimport java.math.BigDecimal;\nimport java.util.Random;\n\nimport org.slf4j.Logger;\nimport org.slf4j.LoggerFactory;\nimport org.springframework.http.ResponseEntity;\nimport org.springframework.stereotype.Component;\n\nimport com.zheng.demo.openapi.products.api.ProductsApiDelegate;\nimport com.zheng.demo.openapi.products.api.model.ProductDO;\n\n@Component\npublic class ProductsApiImpl implements ProductsApiDelegate {\n\tLogger logger = LoggerFactory.getLogger(ProductsApiImpl.class);\n\tprivate final Random rnd = new Random();\n\n\t@Override\n\tpublic ResponseEntity<ProductDO> getProduct(BigDecimal id) {\n\t\tlogger.info(\"getProduct called\");\n\t\tProductDO prod = new ProductDO();\n\t\tprod.setId(id);\n\t\tprod.setName(\"Product_\" + id);\n\t\tprod.setPrice(BigDecimal.valueOf(100.0 + rnd.nextDouble() * 100.0));\n\n\t\treturn ResponseEntity.ok(prod);\n\t}\n\n\t@Override\n\tpublic ResponseEntity<ProductDO> createProduct(ProductDO product) {\n\t\tlogger.info(\"createProduct called\");\n\t\tproduct.setId(BigDecimal.valueOf(rnd.nextDouble() * 10));\n\t\treturn ResponseEntity.ok(product);\n\n\t}\n}\n<\/pre>\n- \n
- line 21, log a statement when
getProduct<\/code> service is called. It is used to verify if the cache is used or not.<\/li>\n- line 32, log a statement when the
createProduct<\/code> service is called.<\/li>\n<\/ul>\n<\/a>3.3 Application.yaml <\/h3>\n
Set the logging application properties and the
base-path<\/code> properties. We use the log statements to verify if the cache data is used or not.<\/div> <\/div><\/p>\napplication.yaml<\/em><\/span><\/p>\n
logging:\n level:\n root: INFO\n org.springframework: INFO\nopenapi:\n product:\n base-path: v1<\/pre>\n
<\/a>4. Generated Source Code<\/h2>\n
Execute the
mvn generate-source<\/code> command and review the generated java source files.<\/p>\n4.1 ApiUtil Class<\/h3>\n
The
ApiUtil<\/code> class has only one static methodsetExampleResponse<\/code>.<\/p>\nApiUtil.java<\/em><\/span><\/p>\n
package com.zheng.demo.openapi.products.api;\n\nimport org.springframework.web.context.request.NativeWebRequest;\n\nimport jakarta.servlet.http.HttpServletResponse;\nimport java.io.IOException;\n\npublic class ApiUtil {\n public static void setExampleResponse(NativeWebRequest req, String contentType, String example) {\n try {\n HttpServletResponse res = req.getNativeResponse(HttpServletResponse.class);\n res.setCharacterEncoding(\"UTF-8\");\n res.addHeader(\"Content-Type\", contentType);\n res.getWriter().print(example);\n } catch (IOException e) {\n throw new RuntimeException(e);\n }\n }\n}\n<\/pre>\nNote<\/strong>: The
ApiUtil.java<\/code> file has the same content when generated from both built-in template and custom template.<\/p>\n4.2 ProductsApi Interface<\/h3>\n
The
ProductsApi<\/code> interface includes 3 defaults methods: <\/p>\n- \n
getDelegate<\/code> is from thedelegatePattern<\/code> setting.<\/li>\ncreateProduct<\/code> andgetProduct<\/code> are defined in theProducts.yaml<\/code> file under theoperation<\/code> section.<\/li>\n<\/ul>\nProductsApi.java<\/em><\/span><\/p>\n
\/**\n * NOTE: This class is auto generated by OpenAPI Generator (https:\/\/openapi-generator.tech) (7.5.0).\n * https:\/\/openapi-generator.tech\n * Do not edit the class manually.\n *\/\npackage com.zheng.demo.openapi.products.api;\n\nimport java.math.BigDecimal;\nimport com.zheng.demo.openapi.products.api.model.ProductDO;\nimport org.springframework.http.ResponseEntity;\nimport org.springframework.validation.annotation.Validated;\nimport org.springframework.web.bind.annotation.*;\nimport org.springframework.web.multipart.MultipartFile;\n\nimport jakarta.validation.Valid;\nimport jakarta.validation.constraints.*;\nimport java.util.List;\nimport java.util.Map;\nimport jakarta.annotation.Generated;\n\n@Generated(value = \"org.openapitools.codegen.languages.SpringCodegen\", date = \"2024-05-04T23:36:23.308233300-05:00[America\/Chicago]\", comments = \"Generator version: 7.5.0\")\n@Validated\npublic interface ProductsApi {\n\n default ProductsApiDelegate getDelegate() {\n return new ProductsApiDelegate() {};\n }\n\n \/**\n * POST \/products : Create a product\n *\n * @param productDO Create a new prodcut in the store (required)\n * @return OK (status code 200)\n *\/\n @RequestMapping(\n method = RequestMethod.POST,\n value = \"\/products\",\n produces = { \"application\/json\" },\n consumes = { \"application\/json\" }\n )\n \n default ResponseEntity<ProductDO> createProduct(\n @Valid @RequestBody ProductDO productDO\n ) {\n return getDelegate().createProduct(productDO);\n }\n\n\n \/**\n * GET \/products\/{id} : Get product detail for a given product id\n *\n * @param id Product's identifier (required)\n * @return OK (status code 200)\n *\/\n @RequestMapping(\n method = RequestMethod.GET,\n value = \"\/products\/{id}\",\n produces = { \"application\/json\" }\n )\n \n default ResponseEntity<ProductDO> getProduct(\n @PathVariable(\"id\") BigDecimal id\n ) {\n return getDelegate().getProduct(id);\n }\n\n}\n<\/pre>\nNote<\/strong>: The
ProductsApi<\/code> file has the same content when generated from both built-in template and custom template.<\/p>\n4.3 ProductApiDelegate Interface<\/h3>\n
The
ProductApiDelegate<\/code> interface has the same methods as theProductApi<\/code> interface.<\/p>\nProductsApiDelegate.java<\/em><\/span><\/p>\n
package com.zheng.demo.openapi.products.api;\n\nimport java.math.BigDecimal;\nimport com.zheng.demo.openapi.products.api.model.ProductDO;\nimport org.springframework.http.HttpStatus;\nimport org.springframework.http.MediaType;\nimport org.springframework.http.ResponseEntity;\nimport org.springframework.web.context.request.NativeWebRequest;\nimport org.springframework.web.multipart.MultipartFile;\n\nimport jakarta.validation.constraints.*;\nimport jakarta.validation.Valid;\nimport java.util.List;\nimport java.util.Map;\nimport java.util.Optional;\nimport jakarta.annotation.Generated;\n\n\/**\n * A delegate to be called by the {@link ProductsApiController}}.\n * Implement this interface with a {@link org.springframework.stereotype.Service} annotated class.\n *\/\n@Generated(value = \"org.openapitools.codegen.languages.SpringCodegen\", date = \"2024-05-04T23:36:23.308233300-05:00[America\/Chicago]\", comments = \"Generator version: 7.5.0\")\npublic interface ProductsApiDelegate {\n\n default Optional<NativeWebRequest> getRequest() {\n return Optional.empty();\n }\n\n \/**\n * POST \/products : Create a product\n *\n * @param productDO Create a new prodcut in the store (required)\n * @return OK (status code 200)\n * @see ProductsApi#createProduct\n *\/\n default ResponseEntity<ProductDO> createProduct(ProductDO productDO) {\n getRequest().ifPresent(request -> {\n for (MediaType mediaType: MediaType.parseMediaTypes(request.getHeader(\"Accept\"))) {\n if (mediaType.isCompatibleWith(MediaType.valueOf(\"application\/json\"))) {\n String exampleString = \"{ \\\"price\\\" : 6.027456183070403, \\\"name\\\" : \\\"name\\\", \\\"id\\\" : 0.8008281904610115 }\";\n ApiUtil.setExampleResponse(request, \"application\/json\", exampleString);\n break;\n }\n }\n });\n return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);\n\n }\n\n \/**\n * GET \/products\/{id} : Get product detail for a given product id\n *\n * @param id Product's identifier (required)\n * @return OK (status code 200)\n * @see ProductsApi#getProduct\n *\/\n default ResponseEntity<ProductDO> getProduct(BigDecimal id) {\n getRequest().ifPresent(request -> {\n for (MediaType mediaType: MediaType.parseMediaTypes(request.getHeader(\"Accept\"))) {\n if (mediaType.isCompatibleWith(MediaType.valueOf(\"application\/json\"))) {\n String exampleString = \"{ \\\"price\\\" : 6.027456183070403, \\\"name\\\" : \\\"name\\\", \\\"id\\\" : 0.8008281904610115 }\";\n ApiUtil.setExampleResponse(request, \"application\/json\", exampleString);\n break;\n }\n }\n });\n return new ResponseEntity<>(HttpStatus.NOT_IMPLEMENTED);\n\n }\n\n}\n<\/pre>\nNote<\/strong>: The OpenAPI built-in template does not know how to transform the
x-spring-cacheable<\/code> extension, so developers must add the@org.springframework.cache.annotation.Cacheable(\"default\")<\/code> annotation to the generated code in order to pass the integration test.<\/p>\n4.4 ProductApiController Class<\/h3>\n
The generated
ProductsApiController<\/code> class has a “openapi.product.base-path<\/code>” property. If the property is not defined, then it falls back to an empty string\"\"<\/code>. Please refer to step 3.3<\/a> as thebase-path<\/code> value is set to “v1<\/code>“.<\/p>\nProductsApiController.java<\/em><\/span><\/p>\n
package com.zheng.demo.openapi.products.api;\n\nimport java.math.BigDecimal;\nimport com.zheng.demo.openapi.products.api.model.ProductDO;\n\n\nimport org.springframework.beans.factory.annotation.Autowired;\nimport org.springframework.http.HttpStatus;\nimport org.springframework.http.MediaType;\nimport org.springframework.http.ResponseEntity;\nimport org.springframework.stereotype.Controller;\nimport org.springframework.web.bind.annotation.PathVariable;\nimport org.springframework.web.bind.annotation.RequestBody;\nimport org.springframework.web.bind.annotation.RequestHeader;\nimport org.springframework.web.bind.annotation.RequestMapping;\nimport org.springframework.web.bind.annotation.CookieValue;\nimport org.springframework.web.bind.annotation.RequestParam;\nimport org.springframework.web.bind.annotation.RequestPart;\nimport org.springframework.web.multipart.MultipartFile;\n\nimport jakarta.validation.constraints.*;\nimport jakarta.validation.Valid;\n\nimport java.util.List;\nimport java.util.Map;\nimport java.util.Optional;\nimport javax.annotation.Generated;\n\n@Generated(value = \"org.openapitools.codegen.languages.SpringCodegen\", date = \"2024-05-04T07:47:53.432603-05:00[America\/Chicago]\")\n@Controller\n@RequestMapping(\"${openapi.product.base-path:}\")\npublic class ProductsApiController implements ProductsApi {\n\n private final ProductsApiDelegate delegate;\n\n public ProductsApiController(@Autowired(required = false) ProductsApiDelegate delegate) {\n this.delegate = Optional.ofNullable(delegate).orElse(new ProductsApiDelegate() {});\n }\n\n @Override\n public ProductsApiDelegate getDelegate() {\n return delegate;\n }\n\n}\n<\/pre>\nNote: The
ProductsApiController<\/code> file has the same content when generated from both built-in template and custom template.<\/p>\n4.5 ProductDO Class<\/h3>\n
The generated
ProductDO<\/code> class defines theProduct<\/code> data model.<\/p>\nProductDO.java<\/em><\/span><\/p>\n
package com.zheng.demo.openapi.products.api.model;\n\nimport java.net.URI;\nimport java.util.Objects;\nimport com.fasterxml.jackson.annotation.JsonProperty;\nimport com.fasterxml.jackson.annotation.JsonCreator;\nimport java.math.BigDecimal;\nimport java.time.OffsetDateTime;\nimport jakarta.validation.Valid;\nimport jakarta.validation.constraints.*;\n\n\nimport java.util.*;\nimport jakarta.annotation.Generated;\n\n\/**\n * Product Information\n *\/\n\n@Generated(value = \"org.openapitools.codegen.languages.SpringCodegen\", date = \"2024-05-04T23:36:23.308233300-05:00[America\/Chicago]\", comments = \"Generator version: 7.5.0\")\npublic class ProductDO {\n\n private BigDecimal id;\n\n private String name;\n\n private BigDecimal price;\n\n public ProductDO id(BigDecimal id) {\n this.id = id;\n return this;\n }\n\n \/**\n * product id\n * @return id\n *\/\n @Valid \n @JsonProperty(\"id\")\n public BigDecimal getId() {\n return id;\n }\n\n public void setId(BigDecimal id) {\n this.id = id;\n }\n\n public ProductDO name(String name) {\n this.name = name;\n return this;\n }\n\n \/**\n * product name\n * @return name\n *\/\n \n @JsonProperty(\"name\")\n public String getName() {\n return name;\n }\n\n public void setName(String name) {\n this.name = name;\n }\n\n public ProductDO price(BigDecimal price) {\n this.price = price;\n return this;\n }\n\n \/**\n * product price value\n * @return price\n *\/\n @Valid \n @JsonProperty(\"price\")\n public BigDecimal getPrice() {\n return price;\n }\n\n public void setPrice(BigDecimal price) {\n this.price = price;\n }\n\n @Override\n public boolean equals(Object o) {\n if (this == o) {\n return true;\n }\n if (o == null || getClass() != o.getClass()) {\n return false;\n }\n ProductDO productDO = (ProductDO) o;\n return Objects.equals(this.id, productDO.id) &&\n Objects.equals(this.name, productDO.name) &&\n Objects.equals(this.price, productDO.price);\n }\n\n @Override\n public int hashCode() {\n return Objects.hash(id, name, price);\n }\n\n @Override\n public String toString() {\n StringBuilder sb = new StringBuilder();\n sb.append(\"class ProductDO {\\n\");\n sb.append(\" id: \").append(toIndentedString(id)).append(\"\\n\");\n sb.append(\" name: \").append(toIndentedString(name)).append(\"\\n\");\n sb.append(\" price: \").append(toIndentedString(price)).append(\"\\n\");\n sb.append(\"}\");\n return sb.toString();\n }\n\n \/**\n * Convert the given object to string with each line indented by 4 spaces\n * (except the first line).\n *\/\n private String toIndentedString(Object o) {\n if (o == null) {\n return \"null\";\n }\n return o.toString().replace(\"\\n\", \"\\n \");\n }\n}\n\n<\/pre>\n<\/a>5. Junit Test Classes<\/h2>\n
5.1 Unit Test<\/h3>\n
ProductsApiImplUnitTest<\/code> has 2 tests which test bothgetProduct<\/code> andcreateProduct<\/code> services.<\/p>\nProductsApiImplUnitTest.java<\/em><\/span><\/p>\n
package com.zheng.demo.openapi.products.service;\n\nimport static org.assertj.core.api.Assertions.assertThat;\n\nimport java.math.BigDecimal;\n\nimport org.junit.jupiter.api.Test;\nimport org.springframework.beans.factory.annotation.Autowired;\nimport org.springframework.boot.test.context.SpringBootTest;\nimport org.springframework.http.ResponseEntity;\n\nimport com.zheng.demo.openapi.products.api.ProductsApi;\nimport com.zheng.demo.openapi.products.api.model.ProductDO;\n\n@SpringBootTest\nclass ProductsApiImplUnitTest {\n\n\t@Autowired\n\tprivate ProductsApi api;\n\n\t@Test\n\tvoid whenGetProduct_then_success() {\n\n\t\tResponseEntity<ProductDO> response = api.getProduct(new BigDecimal(1));\n\t\tassertThat(response).isNotNull();\n\n\t\tassertThat(response.getStatusCode().is2xxSuccessful()).isTrue();\n\n\t}\n\n\t@Test\n\tvoid whenCreateProduct_then_success() {\n\t\tProductDO product = new ProductDO();\n\t\tproduct.setName(\"Test\");\n\t\tproduct.setPrice(new BigDecimal(100));\n\t\tResponseEntity<ProductDO> response = api.createProduct(product);\n\t\tassertThat(response).isNotNull();\n\n\t\tassertThat(response.getStatusCode().is2xxSuccessful()).isTrue();\n\n\t}\n\n}<\/pre>\nExecute the junit tests and both passed as expected.<\/p>\n
5.2 Integration Test<\/h3>\n
ProductsApplicationIntegrationTest<\/code> has 3 tests which test bothgetProduct<\/code> andcreateProduct<\/code> at the test server. ThegetProduct<\/code> should use cache for the same product id.<\/p>\nProductsApplicationIntegrationTest.java<\/em><\/span><\/p>\n
package com.zheng.demo.openapi.products;\n\nimport static org.assertj.core.api.Assertions.assertThat;\n\nimport java.util.stream.Collectors;\nimport java.util.stream.IntStream;\n\nimport org.junit.jupiter.api.Test;\nimport org.springframework.beans.factory.annotation.Autowired;\nimport org.springframework.boot.test.context.SpringBootTest;\nimport org.springframework.boot.test.web.client.TestRestTemplate;\nimport org.springframework.boot.test.web.server.LocalServerPort;\nimport org.springframework.http.HttpEntity;\nimport org.springframework.http.HttpStatus;\nimport org.springframework.http.ResponseEntity;\n\nimport com.zheng.demo.openapi.products.api.model.ProductDO;\n\n@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)\nclass ProductsApplicationIntegrationTest {\n\n\t@LocalServerPort\n\tprivate int port;\n\n\t@Autowired\n\tprivate TestRestTemplate restTemplate;\n\n\t@Test\n\tvoid whenGetProduct_thenSuccess() {\n\t\tResponseEntity<ProductDO> response = restTemplate.getForEntity(\"http:\/\/localhost:\" + port + \"\/v1\/products\/1\",\n\t\t\t\tProductDO.class);\n\t\tassertThat(response.getStatusCode()).isEqualTo(HttpStatus.OK);\n\t}\n\n\t@Test\n\tvoid whenGetProductMultipleTimes_thenResponseCached() {\n\n\t\t\/\/ Call server a few times and collect responses\n\t\tvar quotes = IntStream.range(1, 10).boxed()\n\t\t\t\t.map((i) -> restTemplate.getForEntity(\"http:\/\/localhost:\" + port + \"\/v1\/products\/1\", ProductDO.class))\n\t\t\t\t.map(HttpEntity::getBody).collect(Collectors.groupingBy((q -> q.hashCode()), Collectors.counting()));\n\n\t\tassertThat(quotes.size()).isEqualTo(1);\n\t}\n\n\t@Test\n\tvoid whenCreateProduct_thenSuccess() {\n\t\tProductDO product = new ProductDO();\n\t\tproduct.setName(\"TEST\");\n\t\tResponseEntity<ProductDO> response = restTemplate.postForEntity(\"http:\/\/localhost:\" + port + \"\/v1\/products\",\n\t\t\t\tproduct, ProductDO.class);\n\n\t\tassertThat(response.getStatusCode()).isEqualTo(HttpStatus.OK);\n\t}\n}<\/pre>\nThe
whenGetProductMultipleTimes_thenResponseCached<\/code> test failed as thegetProduct<\/code> service was called multiple times.<\/p>\n2024-05-04T23:28:54.048-05:00 INFO 36452 --- [o-auto-1-exec-2] c.z.d.o.p.service.ProductsApiImpl : createProduct called\n2024-05-04T23:28:54.150-05:00 INFO 36452 --- [o-auto-1-exec-5] c.z.d.o.p.service.ProductsApiImpl : getProduct called\n2024-05-04T23:28:54.164-05:00 INFO 36452 --- [o-auto-1-exec-4] c.z.d.o.p.service.ProductsApiImpl : getProduct called\n2024-05-04T23:28:54.168-05:00 INFO 36452 --- [o-auto-1-exec-1] c.z.d.o.p.service.ProductsApiImpl : getProduct called\n2024-05-04T23:28:54.173-05:00 INFO 36452 --- [o-auto-1-exec-3] c.z.d.o.p.service.ProductsApiImpl : getProduct called\n2024-05-04T23:28:54.178-05:00 INFO 36452 --- [o-auto-1-exec-6] c.z.d.o.p.service.ProductsApiImpl : getProduct called\n2024-05-04T23:28:54.181-05:00 INFO 36452 --- [o-auto-1-exec-7] c.z.d.o.p.service.ProductsApiImpl : getProduct called\n2024-05-04T23:28:54.185-05:00 INFO 36452 --- [o-auto-1-exec-8] c.z.d.o.p.service.ProductsApiImpl : getProduct called\n2024-05-04T23:28:54.189-05:00 INFO 36452 --- [o-auto-1-exec-9] c.z.d.o.p.service.ProductsApiImpl : getProduct called\n2024-05-04T23:28:54.193-05:00 INFO 36452 --- [-auto-1-exec-10] c.z.d.o.p.service.ProductsApiImpl : getProduct called\n2024-05-04T23:28:54.196-05:00 INFO 36452 --- [o-auto-1-exec-2] c.z.d.o.p.service.ProductsApiImpl : getProduct called<\/pre>\n
Note<\/strong>: the
x-spring-cacheable<\/code> is not supported by the default template, therefore thegetProduct<\/code> service is called 10 times instead of one time.<\/p>\n6. Spring Boot OpenAPI Generator Custom Templates<\/h2>\n
As seen in step 5<\/a>, the generated spring boot server stub source code missed the cache annotation. In this step, I will update the built-in
apiDelegate.mustache<\/a><\/code> template to add the “x-spring-cacheable<\/code>” vendor extension and use it when generating the code from theproducts1.yaml<\/code>.<\/p>\n\/*\n* Generated code: do not modify !\n* Custom template with support for x-spring-cacheable extension\n*\/\npackage {{package}};\n\n{{#imports}}import {{import}};\n{{\/imports}}\nimport org.springframework.http.HttpStatus;\nimport org.springframework.http.MediaType;\n{{#useResponseEntity}}\n import org.springframework.http.ResponseEntity;\n{{\/useResponseEntity}}\nimport org.springframework.web.context.request.NativeWebRequest;\nimport org.springframework.web.multipart.MultipartFile;\n{{#reactive}}\n import org.springframework.web.server.ServerWebExchange;\n import reactor.core.publisher.Flux;\n import reactor.core.publisher.Mono;\n import org.springframework.http.codec.multipart.Part;\n{{\/reactive}}\n\n{{#useBeanValidation}}\n import {{javaxPackage}}.validation.constraints.*;\n import {{javaxPackage}}.validation.Valid;\n{{\/useBeanValidation}}\nimport java.util.List;\nimport java.util.Map;\nimport java.util.Optional;\n{{#async}}\n import java.util.concurrent.CompletableFuture;\n{{\/async}}\nimport {{javaxPackage}}.annotation.Generated;\n\n{{#operations}}\n \/**\n * A delegate to be called by the {@link {{classname}}Controller}}.\n * Implement this interface with a {@link org.springframework.stereotype.Service} annotated class.\n *\/\n {{>generatedAnnotation}}\n public interface {{classname}}Delegate {\n {{#jdk8-default-interface}}\n\n default Optional<NativeWebRequest> getRequest() {\n return Optional.empty();\n }\n {{\/jdk8-default-interface}}\n\n {{#operation}}\n \/**\n * {{httpMethod}} {{{path}}}{{#summary}} : {{.}}{{\/summary}}\n {{#notes}}\n * {{.}}\n {{\/notes}}\n *\n {{#allParams}}\n * @param {{paramName}} {{description}}{{#required}} (required){{\/required}}{{^required}} (optional{{#defaultValue}}, default to {{.}}{{\/defaultValue}}){{\/required}}\n {{\/allParams}}\n * @return {{#responses}}{{message}} (status code {{code}}){{^-last}}\n * or {{\/-last}}{{\/responses}}\n {{#isDeprecated}}\n * @deprecated\n {{\/isDeprecated}}\n {{#externalDocs}}\n * {{description}}\n * @see <a href=\"{{url}}\">{{summary}} Documentation<\/a>\n {{\/externalDocs}}\n * @see {{classname}}#{{operationId}}\n *\/\n {{#isDeprecated}}\n @Deprecated\n {{\/isDeprecated}}\n {{#vendorExtensions.x-spring-cacheable}}\n @org.springframework.cache.annotation.Cacheable({{#name}}\"{{.}}\"{{\/name}}{{^name}}\"default\"{{\/name}})\n {{\/vendorExtensions.x-spring-cacheable}}\n {{#jdk8-default-interface}}default {{\/jdk8-default-interface}}{{>responseType}} {{operationId}}({{#allParams}}{{^isFile}}{{^isBodyParam}}{{>optionalDataType}}{{\/isBodyParam}}{{#isBodyParam}}{{^reactive}}{{{dataType}}}{{\/reactive}}{{#reactive}}{{^isArray}}Mono<{{{dataType}}}>{{\/isArray}}{{#isArray}}Flux<{{{baseType}}}>{{\/isArray}}{{\/reactive}}{{\/isBodyParam}}{{\/isFile}}{{#isFile}}{{#isArray}}List<{{\/isArray}}{{#reactive}}Flux<Part>{{\/reactive}}{{^reactive}}MultipartFile{{\/reactive}}{{#isArray}}>{{\/isArray}}{{\/isFile}} {{paramName}}{{^-last}},\n {{\/-last}}{{\/allParams}}{{#reactive}}{{#hasParams}},\n {{\/hasParams}}ServerWebExchange exchange{{\/reactive}}{{#vendorExtensions.x-spring-paginated}}{{#hasParams}}, {{\/hasParams}}{{^hasParams}}{{#reactive}}, {{\/reactive}}{{\/hasParams}}final Pageable pageable{{\/vendorExtensions.x-spring-paginated}}){{#unhandledException}} throws Exception{{\/unhandledException}}{{^jdk8-default-interface}};{{\/jdk8-default-interface}}{{#jdk8-default-interface}} {\n {{>methodBody}}\n }{{\/jdk8-default-interface}}\n\n {{\/operation}}\n }\n{{\/operations}}\n<\/pre>\n- \n
- line 73-75: support the
x-spring-cacheable<\/code> vendor-specific extension.<\/li>\n<\/ul>\n6.1 Use Products1.yaml<\/h3>\n
Update the
pom.xml<\/code> to specifytemplateResourcePath<\/code> with the custom template and useproducts1.xml<\/code>. As you seen at step 2<\/a>, theproducts1.yaml<\/code> includesx-spring-cacheable: true<\/code><\/p>\nUpdated pom.xml at the configuration section<\/em><\/span><\/p>\n
<configuration>\n\t\t\t\t\t\t\t<inputSpec>\n\t\t\t\t\t\t\t\t${project.basedir}\/src\/main\/resources\/api\/products1.yaml<\/inputSpec>\n\t\t\t\t\t\t\t<generatorName>spring<\/generatorName>\n\t\t\t\t\t\t\t<supportingFilesToGenerate>ApiUtil.java<\/supportingFilesToGenerate>\n\t\t\t\t\t\t\t<templateResourcePath>\n\t\t\t\t\t\t\t\t${project.basedir}\/src\/main\/resources\/templates\/JavaSpring\n\t\t\t\t\t\t\t<\/templateResourcePath>\n\t\t\t\t\t\t\t<globalProperties>\n\t\t\t\t\t\t\t\t<debugOpenAPI>true<\/debugOpenAPI>\n\t\t\t\t\t\t\t<\/globalProperties>\n\t\t\t\t\t\t\t<configOptions>\n\t\t\t\t\t\t\t\t<delegatePattern>true<\/delegatePattern>\n\t\t\t\t\t\t\t\t<apiPackage>com.zheng.demo.openapi.products.api<\/apiPackage>\n\t\t\t\t\t\t\t\t<modelPackage>\n\t\t\t\t\t\t\t\t\tcom.zheng.demo.openapi.products.api.model<\/modelPackage>\n\t\t\t\t\t\t\t\t<documentationProvider>source<\/documentationProvider>\n\t\t\t\t\t\t\t\t<dateLibrary>java8<\/dateLibrary>\n\t\t\t\t\t\t\t\t<openApiNullable>false<\/openApiNullable>\n\t\t\t\t\t\t\t\t<useJakartaEe>true<\/useJakartaEe>\n\t\t\t\t\t\t\t\t<useSpringBoot3>true<\/useSpringBoot3>\n\t\t\t\t\t\t\t<\/configOptions><\/pre>\nNote<\/strong>: line 7 specifies the
templateResourcePath<\/code> file location.<\/p>\n6.2 Re-generate the Source<\/h3>\n
- line 32, log a statement when the
- The
- line 63: config the
- Create an OpenAPI specification –