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.

endpoint.xml 
<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:

  • general swagger information

  • common http answers for a specific http code

  • security expressions

  • cache strategies


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


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

  • No labels