Intro
After adding modularity to the backend template we can divide spec(spec.xml) and api(controller.xml, endpoint.xml). Spec is a general specification for our entire API
The purpose of this division is define server information, swagger, general dtos, enums, constraints, constraint's messages into a separate module
...
Structure
module consists of:
resources
shared
Resources have general responses/requests which can be used in other modules and contained in this way(spec/__def__/models)
All constraints, enums, requests/responses from spec module you can reuse in other modules, e.g.
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
<endpoint xmlns="http://www.knubisoft.com/api/schema/endpoint">
<swagger>
<operationId>login</operationId>
<summary>Logging in</summary>
<description>Logging in with user credentials</description>
<tags>
<tag>Login</tag>
</tags>
</swagger>
<responses>
<_200>Success HTTP response from API with HTTP body</_200>
<_404>Accepted HTTP call request but requested object is NOT FOUND</_404>
</responses>
<post>
<response include="jwtTokensResponse.xml"/>
<request include="loginRequest.xml"/>
</post>
</endpoint>
|
| Info |
|---|
where jwtTokensResponse.xml, loginRequest.xml are located in completely different folder |
Also resources have spec.xml this is a main file that describes:
general swagger information
common http answers for a specific http code
security expressions
cache strategies
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
<spec xmlns="http://www.knubisoft.com/api/schema/spec">
<overview>
<path>/api/v1</path>
<version>0.0.1</version>
<title>Java Backend Template API</title>
<description>Rest API based on java which provides read/write/delete/search operations for JBT project
</description>
</overview>
<servers>
<server url="http://localhost:{port}/">
<description>The local API server</description>
<variables>
<variable name="port" defaultValue="8073">
<allowedValues>
<value>8073</value>
</allowedValues>
</variable>
</variables>
</server>
</servers>
<responses>
<_200>Success HTTP response from API with HTTP body</_200>
<_204>Success HTTP response from API without HTTP body</_204>
<_400>Rejected HTTP call with BAD REQUEST status</_400>
<_401>Rejected HTTP call with BAD REQUEST status</_401>
<_403>Rejected HTTP call with UNAUTHORIZED status. It seems like user should login in to the system before execute calls to private endpoints</_403>
<_404>Accepted HTTP call request but requested object is NOT FOUND</_404>
<_500>Internal server error</_500>
</responses>
<security>
<expression name="baseRights" value="hasAuthority('BASE_RIGHTS')"/>
<expression name="owner" value="hasRole('OWNER')"/>
<expression name="admin" value="hasRole('ADMIN')"/>
<expression name="lawyer" value="hasRole('LAWYER')"/>
<expression name="associate" value="hasRole('ASSOCIATE')"/>
<expression name="client" value="hasRole('CLIENT')"/>
<expression name="permissionRead" value="hasAuthority('view_permissions')"/>
<expression name="permissionWrite" value="hasAuthority('manage_roles')"/>
</security>
<cache>
<strategy name="fiveMinCachePerUser" time="1" unit="minutes" policy="user"/>
<strategy name="oneHourCacheForAll" time="1" unit="hours" policy="all"/>
<strategy name="oneHourCacheForAllWithInitCapacity" time="1" unit="hours" policy="all" initialCapacity="10" maximumSize="200"/>
</cache>
</spec> |
Next we have shared sub-module that contains generated responses/requests, enums and other things described above
There is also stub factory located, you can find out more on this link
...
Run from CLI
To generate DTOs, SwaggerConf and so on you need open a terminal and enter this command:
| Code Block | ||
|---|---|---|
| ||
cmd/app generate spec |
| Info |
|---|
All comands related to generation you can find in this file cmd/app |