Controller

Creating

First of all, you need to create a controller. Let's take an API for working with companies as an example.

First step is to create a folder for our API in api-spec module of JBT, so our path will be api/api-spec/src/main/resources/spec/api. Here a folder named 'company' is created.

Then put the file 'controller.xml' in created directory. Here it is, controller created, let's describe it.

IMPORTANT: controller must have exactly the name specified above. Also folder must be created using the path specified above.

Describing

The file must contain the following tags:

  • <controller>
  • <overview>
  • <public> (optional)
  • <private> (optional)

Tag <overview> must contain tag <description> where you should write a short description of a controller.

Tag <public> usually contains tags <include>. In <include> you should specify operation's name e.g. 'getFirmInformation' (further a folder with this name should be created for an endpoint) as 'value' attribute. Also you may use tag attribute 'weight' with a number passed to it. This attribute is optional and is used for placing @Weight annotation over the generated method with specified value. More info about mentioned attributes and their purpose here.

Tag <private> must also have tag <include>, but also it specifies access level to endpoints, so it has attribute 'alias' for it. It provides the following access levels:

  • baseRights
  • permissionRead
  • permissionWrite
  • admin
  • owner
  • client
  • lawyer
  • associate

There are 'jwt', 'basic' and 'apiKey' with true/false values among other optional attributes in tag <private>. You can find more info about these attributes and their purpose here.

Example

Description example for a controller is given below:

controller.xml 
<controller xmlns="http://www.knubisoft.com/api/schema/controller">
    <overview>
        <description>
            Company API
        </description>
    </overview>

    <public>
        <include value="getCompany"/>
        <include value="getEmployee" weight="2"/>
    </public>

    <private alias="baseRights">
        <include value="addFirmInformation"/>
        <include value="getFirmInformation"/>
        <include value="addCreditCard"/>
        <include value="updateInformation"/>
    </private>
</controller>

Endpoint

Basically, you have different operations in your API. In our case it can be adding a credit card, adding a company info, getting that info or updating it. Since all these actions are different operations, you need to create different endpoint for it. Let's take adding a company info as en example.

Creating

Firstly, you need to create a folder which represents desired operation on the same level as controller.xml was created (in our case it's api/api-spec/src/main/resources/spec/api/company/addFirmInformation). Then put in that directory a file named 'endpoint.xml'

IMPORTANT: the name should be exactly 'endpoint.xml'.

Describing

Your endpoint should starts with <endpoint> tag. It must contain the following tags:

  • <swagger>
  • <responses> (optional)
  • <get> (optional)
  • <post> (optional)
  • <delete> (optional)
  • <put> (optional)
  • <head> (optional)
  • <options> (optional)
  • <patch> (optional)
  • <trace> (optional)

Then you must specify one of these tags to get a correct endpoint. You need to specify at least one and only one tag. Further process may vary depending on the type of your operation (getting info or editing info or deleting and so on). We consider only the most common situations. But firstly let's deal with <swagger>

<swagger> tag must contain:

  • <operationId>
  • <summary>
  • <description>
  • <tags> which must contain <tag>

<operationId> specifies the name of the operation (the method in your API interface will have that name), <description> tells you and others what your endpoint does, <summary> is a brief description. Usage of <tags> can help you group your endpoints by specified tag(s).

<get> and <post> are considered here. For more info about them and other tags see this article.

Now you meet response.xml and request.xml. Don't be scared, they are described in next section.

<get> tag specifies which response should be returned after GET request to the endpoint, so it should have tag <response>. It can contain attribute 'include' which points to the model for a response placed in api/api-spec/src/main/resources/spec/__def__/models/static or be empty. In the last case file 'response.xml' which represents a model for a response should be placed in the directory where your endpoint is situated.

<post> tag in addition to <get> functions may contain a model which should be sent during executing POST request to the endpoint. So it can contain both <response> and <request> tags. As a <response> tag above, <request> tag can contain info about the model in 'include' attribute (file should be situated in the place mentioned above) or in the same folder as endpoint.xml in the file named 'request.xml' (in case of empty tag).

Example


endpoint.xml 
<endpoint xmlns="http://www.knubisoft.com/api/schema/endpoint">

	<swagger>
		<operationId>addFirmInformation</operationId>
		<summary>Add firm information</summary>
		<description>Add firm information</description>
		<tags>
			<tag>Company</tag>
		</tags>
	</swagger>

	<post>
		<response include="firmInformationResponse.xml"/>
		<request/>
	</post>

</endpoint>

Response & request

Both response and request mostly contain an information about an object to which API is intended to work with. So usually it is different data like company name, number of employees, dates of contracts establishment and so on. And all these data can be described in response/request.

Creating

You can create file 'response.xml' ('request.xml') right in the folder where your endpoint.xml is placed (in such case you needn't use 'include' attribute in appropriate tags in endpoint.xml) or you can create it in folder spec/src/main/resources/spec/__def__/models/static and pass its name to 'include' attribute of appropriate tag in endpoint.xml. No matter what you choose, it's up to you.

Describing

For both response and request you need to use tag <class>. It can contain

  • <integer>
  • <double>
  • <string>
  • ...

So you are able to use type which you need. Each of these tags has different attributes (more info here) but they have several one in common. It's 'name' and 'description'. 'name' value is used to generate field with specified name in the class which represents the response/request. 'description' value is needed for you and others to understand why this tag was created and also for swagger. Also you need specifiy 'name' as an attribute of the <class> tag. The representing class will have the specified name. 

IMPORTANT: your name for a class must be written using PascalCase and end with 'Request'/'Response'.

Example


request.xml 
<class name="FirmInformationRequest" xmlns="http://www.knubisoft.com/api/schema/class" >
	<string name="firmName" description="Firm name"/>
	<string name="country" description="Country"/>
	<string name="state" description="State"/>
	<string name="city" description="City "/>
	<string name="firstAddress" description="First address"/>
	<string name="secondAddress" description="Second address"/>
	<integer name="postCode" description="Post code"/>
	<localdate name="establishDate" description="The date of establishing"/>
</class>


Put it all together

As a result you should get the following structure:



If you have any questions/suggestions/remarks feel free to contact Diakonov Serhii. Hope you'll find the article useful =)

  • No labels