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 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.

<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>

where jwtTokensResponse.xml, loginRequest.xml are located in completely different folder

Also resources have spec.xml this is a main file that describes:


<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:

cmd/app generate spec

All comands related to generation you can find in this file cmd/app