Creating APIs‎ > ‎

API Docs

Create Client Code (SDKs) using Swagger-based Tools

You can create client code (SDKs) to make RESTful data easy to consume in your application (for example, Java Plain Old Java Objects (POJOs) or .NET Plain Old CLR Objects (POCOs)) using Swagger-based tools. You can document your API using the built-in Swagger service. Besides API documentation, this drives several tools in the Swagger ecosystem, such as generation of client SDKs.

Note: You can document the behavior of your API using topics. For more information about topics, see Manage Topics.

For more information about Swagger, see the Swagger site.

Access Swagger from one of the following locations in API Creator:

  • The REST Lab.
  • The Execute, API Docs, API documentation tab. Click View Documentation.

Swagger starts by showing a list of APIs. In API Creator, these are your database objects (tables, views and stored procedures) and your custom resources. You can expand the list to list the operations. You can further expand the operations to see the JSON details, as shown in the following image (click the thumbnail to see the full screen):

The Swagger specification for your API is available at the URL specified in the URL box near the Swagger logo. You can use it (possibly with the API key on the URL, for example .../@docs/Customers?auth=MyApiKey:1).

REST APIs

Swagger's popularity has resulted in a rich ecosystem of tools built around Swagger. For more information about the tools available for your API Server, see the Swagger.io websiteFor example, you can generate client-side SDKs for your API using swagger-codegen, which can generate client-side APIs for Java, C#, Scala, Clojure, Dart, Go, Objective-C, Perl, Python, PHP, Ruby, and more.

For example, you can use a swagger-codegen generated API, in this case for Java:

AllCustomersApi allCusts = new AllCustomersApi();

       // Set up the API client (only needs to be done once)
ApiClient client = allCusts.getApiClient();
client.setBasePath("https://rest.acme.com/rest/default/demo/v1");
client.addDefaultHeader("Authorization", "CALiveAPICreator demo_full:1");
client.setDateFormat(new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSS"));

       // Get all the customers
List<AllCustomers> custs = allCusts.allCustomersGet(null, null, null, null, null, null, 
                null, null, null, null, null, null, null, null, null, null);
for (AllCustomers cust : custs) {
System.out.println("Customer: " + cust.getName());
}

For more information about swagger-codegen, see the GitHub site.

Call Swagger in a Browser

You can call the Swagger UI using the Swagger service and passing in the project URL.

Prerequisite: You have allowed the discovery of the API Swagger doc without authentication by selecting the Allow Swagger without authentication checkbox on the Create, API Properties, Settings tab.

For more information about this setting, see API Properties.

For example:

http://localhost:8080/APICreator/swagger-ui/index.html?url=http://localhost:8080/rest/default/demo/v1/%40docs

API Documentation Services

Your API includes endpoints for Swagger generation. The @docs endpoint generates JSON, as shown in the docs.json fileThe following image shows the @docs endpoint on the Execute, REST Lab, Request tab:

You can get details about a specific endpoint using @docs/customers, as shown in the EndPointDetail.json file. The following image shows an example of how to get details using the Execute, REST Lab, Request tab:

Connect to your API

You can get the details on how to connect to your API, including examples, on the Execute, API Docs, Connecting tab.

Get Code Samples

You can get help connecting and returning your REST APIs and view the sample code fragments on the Execute, API Docs, Code samples tab.