First, we need to choose a root folder where we will create all our projects.
To simplify I will use /tmp as the root folder. You can choose any other one you want, it does not matter
but be careful to update the command lines with the right value.
Open a terminal, go into the /tmp folder and create an application folder named Open a terminal, go into the /tmp
folder and create an application folder named openApiWorkshop.
cd /tmp
mkdir openApiWorkshop && cd openApiWorkshop
Once in your project folder, launch JHipster. Fill the questions with the responses below. You can also add the .yo-rc.json provided and launch the JHipster CLI. All the configuration will be loaded from it.
jhipster
? Which *type* of application would you like to create? Monolithic application (recommended for simple projects)
? What is the base name of your application? openApiWorkshop
? What is your default Java package name? io.github.openapiworkshop
? Do you want to use the JHipster Registry to configure, monitor and scale your application? No
? Which *type* of authentication would you like to use? JWT authentication (stateless, with a token)
? Which *type* of database would you like to use? SQL (H2, MySQL, MariaDB, PostgreSQL, Oracle, MSSQL)
? Which *production* database would you like to use? PostgreSQL
? Which *development* database would you like to use? H2 with disk-based persistence
? Do you want to use the Spring cache abstraction? Yes, with the Ehcache implementation (local cache, for a single nod
e)
? Do you want to use Hibernate 2nd level cache? Yes
? Would you like to use Maven or Gradle for building the backend? Maven
? Which other technologies would you like to use? API first development using OpenAPI-generator
? Which *Framework* would you like to use for the client? Angular
? Would you like to use a Bootswatch theme (https://bootswatch.com/)? Default JHipster
? Would you like to enable internationalization support? No
? Besides JUnit and Jest, which testing frameworks would you like to use? (Press <space> to select, <a> to toggle all,
<i> to invert selection)
? Would you like to install other generators from the JHipster Marketplace? No
As you can see at the following question
Which other technologies would you like to use?
We choose API first development using OpenAPI-generator`. JHipster will provide all the configuration we need to use OpenApi and do API-First design.
If you used to use JHipster you will not be surprised by the following generated code. Otherwise I suggest you to take time to understand the architecture. Anyway the code is near from a classic Spring Boot/Angular project.
When we choose the OpenAPI option, JHipster is slightly modified.
- We have the openApi plugin added
<plugin>
<!--
Plugin that provides API-first development using openapi-generator to
generate Spring-MVC endpoint stubs at compile time from an OpenAPI definition file
-->
<groupId>org.openapitools</groupId>
<artifactId>openapi-generator-maven-plugin</artifactId>
</plugin>
- The plugin configuration in the plugin management part.
<plugin>
<!--
Plugin that provides API-first development using openapi-generator to
generate Spring-MVC endpoint stubs at compile time from an OpenAPI definition file
-->
<groupId>org.openapitools</groupId>
<artifactId>openapi-generator-maven-plugin</artifactId>
<version>${openapi-generator-maven-plugin.version}</version>
<executions>
<execution>
<goals>
<goal>generate</goal>
</goals>
<configuration>
<inputSpec>${project.basedir}/src/main/resources/swagger/api.yml</inputSpec>
<generatorName>spring</generatorName>
<apiPackage>io.github.openapiworkshop.web.api</apiPackage>
<modelPackage>io.github.openapiworkshop.web.api.model</modelPackage>
<supportingFilesToGenerate>ApiUtil.java</supportingFilesToGenerate>
<importMappings>Problem=org.zalando.problem.Problem</importMappings>
<skipValidateSpec>false</skipValidateSpec>
<configOptions>
<delegatePattern>true</delegatePattern>
<title>open-api-workshop</title>
</configOptions>
</configuration>
</execution>
</executions>
</plugin>
- The plugin execution in the build part
<pluginExecution>
<pluginExecutionFilter>
<groupId>org.openapitools</groupId>
<artifactId>openapi-generator-maven-plugin</artifactId>
<versionRange>${openapi-generator-maven-plugin.version}</versionRange>
<goals>
<goal>generate</goal>
</goals>
</pluginExecutionFilter>
<action>
<ignore />
</action>
</pluginExecution>
At the following path src/main/resources/swagger/api.yaml the api.yaml file contain a sample api file, which
will be used to define our API contracts.
This is the heart of our API-First Design.
By default, JHipster provide a 3.0.x api.yaml file, it's possible to use a 2.0.x definition in place.
# API-first development with OpenAPI
# This file will be used at compile time to generate Spring-MVC endpoint stubs using openapi-generator
openapi: '3.0.1'
info:
title: 'openApiWorkshop'
version: 0.0.1
servers:
- url: http://localhost:8080/api
description: Development server
- url: https://localhost:8080/api
description: Development server with TLS Profile
paths: {}
components:
securitySchemes:
jwt:
type: http
description: JWT Authentication
scheme: bearer
bearerFormat: JWT
security:
- jwt: []
In your terminal, write
./mvnw
This will launch both frontend and backend application that will be reachable at the following URL http://localhost:8080.
When the following message appear in your teminal, the application is ready !
----------------------------------------------------------
Application 'openApiWorkshop' is running! Access URLs:
Local: http://localhost:8080/
External: http://10.92.16.43:8080/
Profile(s): [dev, swagger]
----------------------------------------------------------
After been identified in the application the admin account (admin/admin), open the API menu.
You should see the swagger-ui with all default JHipster API generated.
You are now ready to generate your own API ! >>> next