View Source

Intro

After adding modularity to the backend template we can divide spec(spec.xml) and api. 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)

Backend Template > Spec module > image2023-8-3_17-9-45.png

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

<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

Backend Template > Spec module > image2023-8-7_11-59-36.png

There is also stub factory located, you can find out more on this link