cisco.radkit.swagger module – Interacts with Swagger/OpenAPI endpoints via RADKit

Note

This module is part of the cisco.radkit collection (version 2.0.0).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install git+https://wwwin-github.cisco.com/scdozier/cisco.radkit-ansible.git. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: cisco.radkit.swagger.

New in cisco.radkit 0.3.0

Synopsis 

Provides comprehensive interaction with Swagger/OpenAPI endpoints through RADKit
Supports all standard HTTP methods with automatic request/response handling
Includes proper status code validation and JSON response processing
Automatically updates Swagger paths before making requests
Designed for network device API automation and integration

Requirements 

The below requirements are needed on the host that executes this module.

radkit

Parameters 

Parameter	Comments
client_ca_path string	Alternate path to client ca cert for RADKIT If the value is not specified in the task, the value of environment variable RADKIT_ANSIBLE_CLIENT_CA_PATH will be used instead.
client_cert_path string	Alternate path to client cert for RADKIT If the value is not specified in the task, the value of environment variable RADKIT_ANSIBLE_CLIENT_CERT_PATH will be used instead.
client_key_password_b64 aliases: radkit_client_private_key_password_base64 string / required	Client certificate password in base64 If the value is not specified in the task, the value of environment variable RADKIT_ANSIBLE_CLIENT_PRIVATE_KEY_PASSWORD_BASE64 will be used instead.
client_key_path string	Alternate path to client key for RADKIT If the value is not specified in the task, the value of environment variable RADKIT_ANSIBLE_CLIENT_KEY_PATH will be used instead.
content string	Raw request body content as string or bytes Mutually exclusive with ‘json’ and ‘data’ parameters
cookies dictionary	Cookie values to include in the request Provided as a dictionary of cookie names and values
data dictionary	Data to be form-encoded and sent in the request body Mutually exclusive with ‘json’ and ‘content’ parameters
device_name string / required	Name of device as it shows in RADKit inventory
files dictionary	Files to upload with the request (multipart form data) Can be used alone or with ‘data’ parameter
headers dictionary	Custom HTTP headers to include in the request Common headers include ‘Content-Type’, ‘Authorization’, etc.
identity aliases: radkit_identity string / required	Identity to authentiate with RADKit (xxxx@cisco.com). If the value is not specified in the task, the value of environment variable RADKIT_ANSIBLE_IDENTITY will be used instead.
json dictionary	Request body to be JSON-encoded and sent with appropriate Content-Type Mutually exclusive with ‘content’ and ‘data’ parameters
method string / required	HTTP method (get,post,put,patch,delete,options,head)
parameters dictionary	Path parameters for the Swagger path (e.g., for /users/{userId}) Provided as a dictionary of parameter names and values
params dictionary	URL query parameters to append to the request Will be properly URL-encoded and appended to the path
path string / required	url path, starting with /
service_serial aliases: radkit_serial, radkit_service_serial string / required	Radkit service serial If the value is not specified in the task, the value of environment variable RADKIT_ANSIBLE_SERVICE_SERIAL will be used instead.
status_code list / elements=integer	A list of valid, numeric, HTTP status codes that signifies success of the request. Default: `[200]`
timeout float	Timeout for the request on the Service side, in seconds If not specified, the Service default timeout will be used

Examples 

- name: Get alarms from vManage
  cisco.radkit.swagger:
    device_name: vmanage1
    path: /alarms
    method: get
    status_code: [200]
  register: swagger_output
  delegate_to: localhost

- name: Register a new NMS partner in vManage with path parameters
  cisco.radkit.swagger:
    device_name: vmanage1
    path: /partner/{partnerType}
    parameters:
      partnerType: "dnac"
    method: post
    status_code: [200]
    json:
      name: "DNAC-test"
      partnerId: "dnac-test"
      description: "dnac-test"
    headers:
      Authorization: "Bearer {{ auth_token }}"
  register: swagger_output
  delegate_to: localhost

- name: Upload configuration file
  cisco.radkit.swagger:
    device_name: device1
    path: /config/upload
    method: post
    files:
      config: "{{ config_file_path }}"
    data:
      description: "New configuration"
    timeout: 60.0
  register: upload_result
  delegate_to: localhost

- name: Get device status with query parameters
  cisco.radkit.swagger:
    device_name: device1
    path: /status
    method: get
    params:
      format: json
      verbose: true
    headers:
      Accept: application/json
    cookies:
      sessionid: "{{ session_id }}"
  register: status_result
  delegate_to: localhost

- name: Send raw content data
  cisco.radkit.swagger:
    device_name: device1
    path: /config/raw
    method: put
    content: |
      interface GigabitEthernet0/1
       ip address 192.168.1.1 255.255.255.0
       no shutdown
    headers:
      Content-Type: text/plain
  register: config_result
  delegate_to: localhost

Return Values 

Common return values are documented here, the following are the fields unique to this module:

Key	Description
content_type string	HTTP response Content-Type header Returned: success
cookies dictionary	HTTP response cookies Returned: when cookies are present in response
data string	response body content as string Returned: success
headers dictionary	HTTP response headers Returned: success
json dictionary	response body content decoded as json Returned: when response contains valid JSON
method string	The HTTP method that was used Returned: success
status_code integer	HTTP response status code Returned: success
url string	The complete URL that was requested Returned: success

Authors

Scott Dozier (@scdozier)

cisco.radkit.swagger module – Interacts with Swagger/OpenAPI endpoints via RADKit

Synopsis

Requirements

Parameters

Examples

Return Values