...
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:
...
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
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
<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
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 =)