Connections > Swagger file generation for REST V2 connections > Generating a Swagger file
  

Generating a Swagger file

You can generate a swagger file for REST V2 connections from the Swagger Files page in Administrator.
    1. Click New.
    2. Enter a name and description for the swagger file.
    3. Specify the swagger details. The following table describes parameters to create a swagger file:
    Parameter
    Description
    Runtime Environment
    Mandatory. Name of the runtime environment used to generate the swagger file.
    URL
    Mandatory. URL consists of the host name and port number. For example: http://localhost:8000
    Verb
    Select the REST method being used by the web service. The supported methods are: GET, POST, PUT, and DELETE.
    Authentication Type
    If required, select the authentication method to login to the web service application. Default is none.
    API Base Path
    The path on which the API is served. The base path is the one specified after the hostname and port. For example, if the REST web service URL is http://localhost:8000/greetings/hello?Status=GoodMorning, the base path will be /greetings.
    API Path
    The path specified after the base path is API path. For example, if the REST web service URL is http://localhost:8000/greetings/hello?Status=GoodMorning, the API path will be /hello?Status=GoodMorning.
    To define a path parameter, enclose the path, which is being treated as variable with curly brackets {}.
    For example, if the REST web service URL is https://localhost:8080/sample/Stringoperation/concat/str1/str2?id=123 and concat is a variable in this path, define the API path as below:
    Stringoperation/{concat}/str1/str2?id=123
    You can define any number of path parameters.
    Note: The API path can include the query parameters. If you define the query parameters with the API path, do not specify the query parameters in the Query Params field.
    Username
    The user name to login to the web service application.
    Required for Basic and Digest authentication types.
    Password
    The password associated with the user name.
    Required for Basic and Digest authentication types.
    Token
    The access token to connect to the web service application.
    Required only for OAuth authentication type.
    Token Secret
    The password associated with the OAuth token.
    Required for OAuth authentication type.
    Consumer Key
    The client key associated with the web service application.
    Required for OAuth authentication type.
    Consumer Secret
    The client password to connect to the web service application.
    Required only for OAuth authentication type.
    Accept
    Select the MIME type.
    Headers
    Define header parameters in JSON format. For example: {"Accept-Charset":"utf-8"}
    Query Params
    Provide query parameters in JSON format. For example: {"name":"subject","description":"The subject to be greeted."}
    Defining query parameters in the Query Params field adds the query parameters as input parameters in the Swagger specification file.
    If you define the query parameters in Query Params, do not specify the query parameters in the API Path field.
    Operation ID
    Mandatory. A unique text identifier for the API path.
    Content Type
    Select the MIME type.
    Raw Body
    Enter the request body content. If you select application/x-www-form-urlencoded in the content type, specify the raw body parameters in the key-value pair. Each key-value pair starts with a new line. Example:
    a : b
    c : d
    e : f
    Not applicable to the GET method.
    JSON Response File
    Optional. Upload the JSON response file if you want to generate the swagger definition from the response file. No call is made to the REST endpoint if you select the JSON response file.
    If you do not provide the JSON response file, a call is made to the REST endpoint to fetch the response for generating swagger definition.
    Note: For information about the swagger definition objects and fields supported by REST V2 Connector, see the REST V2 Connector documentation.
    4. Click Save to generate the swagger file. An entry for the swagger file appears in the Swagger Files page.
    In case of failure while connecting to the web service, the fault response obtained from the web service is logged in the Swagger Files page.
    5. Click the download icon to save the Swagger file in a local directory.
    To use the swagger file in the REST V2 connection, copy the file to the Secure Agent system where you will create a REST V2 connection.