Document and test your REST API using OpenAPI/Swagger support in TMS XData

Bookmarks: 

Tuesday, October 10, 2017

TMS XData 2.7 has been just release with lots of new features. The most interesting one, in my opinion, is OpenAPI/Swagger support.

TMS XData server can now optionally provide a JSON file containing the OpenAPI Specification (OAS, formerly Swagger) for your whole server API. This opens up a lot of possibilities, usage of several tools of the OpenAPI ecosystem is now possible. Main one would be the Swagger UI, a web front-end to describe and test your API.

Enabling support for OpenAPI

To enable OpenAPI support in your server, just use the unit XData.OpenAPI.Service and call the method RegisterOpenAPIService anywhere in your application:
uses {...}, XData.OpenAPI.Service;
 
{...}
  RegisterOpenAPIService;
It's as simple as that. XData will scan your whole API and build the specification file describing that API automatically. The specification will be very detailed as XData has all the metadata for your API: the method parameters, the mappings for entity classes, the data types, etc.

Retrieving the OpenAPI Specification (OAS) file

The OAS file is available through a GET request to the URL "/openapi/swagger.json" relative to your server root URL. For example, if your server root is http://myserver/tms/xdata/, then you will be able to access the file from this URL:

GET http://myserver/tms/xdata/openapi/swagger.json

Using Swagger UI

One of the main use cases is to be able to use the Swagger UI. It's a web-based front-end to dynamically document and test your API. From their website: "Swagger UI allows anyone - be it your development team or your end consumers - to visualize and interact with the API's resources without having any of the implementation logic in place. It's automatically generated from your Swagger specification, with the visual documentation making it easy for back end implementation and client side consumption.".

You can visit their site for more information, but here are quick steps to see it in action from your own server:

1. Create your XData Server and enable OpenAPI support as described above.

2. Enable CORS in your TXDataServerModule:
    Module.AccessControlAllowOrigin := '*';
3. Open the existing live demo of the Swagger UI at https://petstore.swagger.io.

4. In the edit box that appears at the top of the page, just type the URL that returns the OpenAPI Specification. For example, "http://myserver/tms/xdata/openapi/swagger.json", and click "Explore". That would be enough to list your API.

If you want an even faster way to see it in action with XData:

1. Run the demo named SQLiteConsoleServer. It's located in folder demossimple_sqlite. That demo is available when you install TMS XData trial or licensed version.

2. Open web site https://petstore.swagger.io.

3. In the edit box, enter the OAS file address: "http://localhost:2001/tms/music/openapi/swagger.json":



4. Click Explore to browse the API and test.



And that's it!

This new XData release doesn't stop there, there are lots of new features including several new types supported in method parameters, entity properties, PODO properties, and more!


Wagner R. Landgraf


Bookmarks: 

This blog post has not received any comments yet.



Add a new comment:
Author:
Email:
  You will receive a confirmation mail with a link to validate your comment, so please use a valid email address.
Comment:
 
Change Image
Fill in the characters from the image above:
 

All fields are required.
 




Previous  |  Next  |  Index