Access OpenAPI (Swagger) Documentation for your API

Access OpenAPI (Swagger) Documentation for your API
lac52
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 Swagger service that 
Layer7 Live API Creator
 includes. In addition to API documentation, the Swagger service drives several tools in the Swagger ecosystem, such as generation of client SDKs.
For more information about Swagger, see the Swagger site.
In this article:
 
 
2
 
 
Access OpenAPI (Swagger)
You can access OpenAPI (Swagger) in API Creator from the following locations in API Creator:
Access Swagger from the REST Lab
Your API includes endpoints for Swagger generation. You can retrieve the Swagger documentation for your API or you can get details about a specific endpoint.
Follow these steps:
 
  1. With your API open, in the Tools section, click 
    REST Lab
    .
  2. Complete the following, and then send your request by clicking 
    GET
    :
    1. Select 
      Metadata
       as the endpoint on which you want to operate.
    2. Select 
      @docs
       as the metadata endpoint.
    For example, to retrieve the OpenAPI (Swagger) documentation for your API, use the following URL:
    http://myserver.acme.com/rest/acme/proj1/v1/@docs
    For more information about the 
    @docs
     RESTful endpoint, see System REST Endpoints.
The JSON response appears in the 
Response
 section of the page.
Access Swagger from the API Documentation Tab
You can access OpenAPI (Swagger) API documentation from the 
API Documentation
 tab. To view this tab, in the Tools section, click 
API Docs
, and then click the 
API Documentation
 tab. Swagger starts by showing a list of APIs. The Swagger documentation shows your database objects (tables, views, and stored procedures) and the table-based resources that you defined explicitly in API Creator. You can expand the list to list the operations. To view the JSON details, expand the operations. The following image shows the GET operation expanded on the API Documentation page:
 
 
The generated OpenAPI (Swagger) document reflects the endpoints to which the 
API Documentation
 role has access. If you do not want 
Layer7 Live API Creator
 to reflect your API in the OpenAPI (Swagger) document, change the 
API Documentation
 role to include or exclude the parts of your API from that role.
For more information about how to include and exclude parts of an API from roles, see Authorization and Role-Based Endpoint Access.
Access Swagger from a Browser
You can access the OpenAPI (Swagger) API documentation directly from a browser.
Prerequisite:
 You have enabled access to Swagger documentation without authentication (the 
Allow Swagger without authentication
 checkbox is selected).
Call using a URL similar to the following:
https://myserver.acme.com/rest/acme/proj1/v1/@docs
For more information:
View References for your API
You can view the references for your API in API Creator from the 
Connecting
 tab. This tab displays references, such as how to authenticate, and details on how to connect to your API, including examples. To view this tab, with your API open, in the Tools section, click 
API Docs
. The 
Connecting
 tab displays by default.
The following image shows an example of the authentication requirement:
 Screen%2520Shot%25202016-06-22%2520at%25205.14.02%2520PM.png 
View Code Samples for Connecting to and Returning your REST API
You can get help connecting and returning your REST APIs and view the sample code fragments. The code samples display on the 
Code samples
 tab. To view this tab, from the 
Connecting
 tab, click the 
Code samples
 tab.
Access the OpenAPI Specification for your API
You can access the OpenAPI specification for your API using the URL that is specified in the URL box near the Swagger logo on the 
API Documentation
 tab. You can use the URL, possibly with the API key, for example:
.../@docs?auth=MyApiKey:1
Generate a Client-Side SDK for your API Using the Swagger Codegen Project
OpenAPI (Swagger)'s popularity has resulted in a rich ecosystem of tools that are built around Swagger. For example, you can generate client-side SDKs for your API using swagger-codegen, which can generate client-side APIs for API client languages, such as Java, C#, Scala, Clojure, Dart, Go, Objective-C, Perl, Python, PHP, and Ruby.
The following code snippet shows an example of setting up the API client 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: