docs(APIv2): RHINENG-14358 spec documentation

spec/api/v2/openapi.rb

@@ -46,12 +46,10 @@ def info
       end
 
       def description
-        'UNDER DEVELOPMENT: This version of the API is not fully done ' \
-          'and some parts of it might change! ' \
-          'This is the API for Cloud Services for RHEL Compliance. ' \
-          'You can find out more about Red Hat Cloud Services for RHEL at ' \
-          '[https://console.redhat.com/]' \
-          '(https://console.redhat.com/)'
+        'This is the API for Cloud Services for RHEL Compliance. ' \
+        'You can find out more about Red Hat Cloud Services for RHEL at ' \
+        '[https://console.redhat.com/]' \
+        '(https://console.redhat.com/)'
       end
     end
   end

spec/integration/v2/policies_spec.rb

@@ -14,7 +14,8 @@
     get 'Request Policies' do
       v2_auth_header
       tags 'Policies'
-      description 'Lists Policies'
+      description 'Retrieve the list of policies that have been created ' \
+                  'to test the compliance of your registered systems.'
       operationId 'Policies'
       content_types
       pagination_params_v2
@@ -70,7 +71,7 @@
     post 'Create a Policy' do
       v2_auth_header
       tags 'Policies'
-      description 'Create a Policy with the provided attributes'
+      description 'Create a new security policy.'
       operationId 'CreatePolicy'
       content_types
 
@@ -102,7 +103,7 @@
     get 'Request a Policy' do
       v2_auth_header
       tags 'Policies'
-      description 'Returns a Policy'
+      description 'Retrieve a specific policy.'
       operationId 'Policy'
       content_types
 
@@ -130,7 +131,7 @@
     patch 'Update a Policy' do
       v2_auth_header
       tags 'Policies'
-      description 'Updates a Policy with the provided attributes'
+      description 'Edit or update an existing policy.'
       operationId 'UpdatePolicy'
       content_types
 
@@ -152,7 +153,7 @@
     delete 'Delete a Policy' do
       v2_auth_header
       tags 'Policies'
-      description 'Deletes a Policy'
+      description 'Delete a specific policy.'
       operationId 'DeletePolicy'
       content_types
 
@@ -186,7 +187,7 @@
     get 'Request Policies assigned to a System' do
       v2_auth_header
       tags 'Systems'
-      description 'Lists Policies under a System'
+      description 'List all policies assigned to a single system.'
       operationId 'SystemsPolicies'
       content_types
       pagination_params_v2

spec/integration/v2/profiles_spec.rb

@@ -15,7 +15,7 @@
     get 'Request Profiles' do
       v2_auth_header
       tags 'Content'
-      description 'Lists Profiles'
+      description 'List all security guide profiles.'
       operationId 'Profiles'
       content_types
       pagination_params_v2
@@ -77,7 +77,7 @@
     get 'Request a Profile' do
       v2_auth_header
       tags 'Content'
-      description 'Returns a Profile'
+      description 'Retrieve a specific profile.'
       operationId 'Profile'
       content_types
 

spec/integration/v2/reports_spec.rb

@@ -21,7 +21,7 @@
     get 'Request Reports' do
       v2_auth_header
       tags 'Reports'
-      description 'Lists Reports'
+      description 'Retrieve a list of all available reports.'
       operationId 'Reports'
       content_types
       pagination_params_v2
@@ -101,7 +101,7 @@
     get 'Request a Report' do
       v2_auth_header
       tags 'Reports'
-      description 'Returns a Report'
+      description 'Retrieve a specific report.'
       operationId 'Report'
       content_types
 
@@ -129,7 +129,7 @@
     delete 'Delete a Report results' do
       v2_auth_header
       tags 'Reports'
-      description "Deletes Report's test results"
+      description 'Delete test results for a specific report.'
       operationId 'DeleteReport'
       content_types
 
@@ -205,7 +205,7 @@
     get 'Request Reports' do
       v2_auth_header
       tags 'Reports'
-      description 'Lists Reports'
+      description 'Retrieve a list of reports for a specific system.'
       operationId 'SystemReports'
       content_types
       pagination_params_v2

spec/integration/v2/rule_groups_spec.rb

@@ -15,7 +15,7 @@
     get 'Request Rule Groups' do
       v2_auth_header
       tags 'Content'
-      description 'Lists Rule Groups'
+      description 'List all rules groups.'
       operationId 'Rule Groups'
       content_types
       pagination_params_v2
@@ -68,7 +68,7 @@
     get 'Request a Rule Group' do
       v2_auth_header
       tags 'Content'
-      description 'Returns a Rule Group'
+      description 'Retrieve a specific rule group.'
       operationId 'RuleGroup'
       content_types
 

spec/integration/v2/rule_results_spec.rb

@@ -33,7 +33,7 @@
     get 'Request Rule Results under a Report' do
       v2_auth_header
       tags 'Reports'
-      description 'Lists Rule Results under a Report'
+      description 'Retrieve all of the rule results for a specific report.'
       operationId 'ReportRuleResults'
       content_types
       pagination_params_v2

spec/integration/v2/rules_spec.rb

@@ -16,7 +16,7 @@
     get 'Request Rules' do
       v2_auth_header
       tags 'Content'
-      description 'Lists Rules assigned'
+      description 'Retrieve a list of rules for a specific security guide.'
       operationId 'Rules'
       content_types
       pagination_params_v2
@@ -69,7 +69,7 @@
     get 'Request a Rule' do
       v2_auth_header
       tags 'Content'
-      description 'Returns a Rule'
+      description 'Retrieve a specific rule from a specific security guide.'
       operationId 'Rule'
       content_types
 
@@ -110,7 +110,7 @@
     get 'Request Rules assigned to a Profile' do
       v2_auth_header
       tags 'Content'
-      description 'Lists Rules assigned to a Profile'
+      description 'Retrieve a list of all security guide rules for a specific profile.'
       operationId 'ProfileRules'
       content_types
       pagination_params_v2
@@ -164,7 +164,7 @@
     get 'Request a Rule assigned to a Profile' do
       v2_auth_header
       tags 'Content'
-      description 'Returns a Rule assigned to a Profile'
+      description 'Retrieve a specific security guide rule for a specific profile.'
       operationId 'ProfileRule'
       content_types
 
@@ -223,7 +223,7 @@
     get 'Request Rules assigned to a Tailoring' do
       v2_auth_header
       tags 'Policies'
-      description 'Lists Rules assigned to a Tailoring'
+      description 'Retrieve a list of rules relating to specific tailorings.'
       operationId 'TailoringRules'
       content_types
       pagination_params_v2
@@ -318,7 +318,7 @@
 
       v2_auth_header
       tags 'Policies'
-      description 'Assigns a Rule to a Tailoring'
+      description 'Add a rule to a specific tailoring.'
       operationId 'AssignRule'
       content_types
 
@@ -355,7 +355,7 @@
 
       v2_auth_header
       tags 'Policies'
-      description 'Unassigns a Rule from a Tailoring'
+      description 'Use this to remove a rule from your tailoring.'
       operationId 'UnassignRule'
       content_types
 

spec/integration/v2/security_guides_spec.rb

@@ -13,7 +13,7 @@
     get 'Request Security Guides' do
       v2_auth_header
       tags 'Content'
-      description 'Lists Security Guides'
+      description 'Retrieve a list of all SCAP security guides.'
       operationId 'SecurityGuides'
       content_types
       pagination_params_v2
@@ -95,7 +95,7 @@
     get 'Request a Security Guide' do
       v2_auth_header
       tags 'Content'
-      description 'Returns a Security Guide'
+      description 'Retrieve a specific security guide.'
       operationId 'SecurityGuide'
       content_types
 
@@ -127,9 +127,10 @@
     get 'Request the Rule Tree of a Security Guide' do
       v2_auth_header
       tags 'Content'
-      description 'Returns the Rule Tree of a Security Guide'
+      description 'Returns rule tree of a security guide.'
       operationId 'SecurityGuideRuleTree'
       content_types
+      deprecated true
 
       parameter name: :security_guide_id, in: :path, type: :string, required: true
 

spec/integration/v2/supported_profiles_spec.rb

@@ -13,7 +13,7 @@
     get 'Request Supported Profiles' do
       v2_auth_header
       tags 'Content'
-      description 'Lists Supported Profiles'
+      description 'Retrieve the list of profiles supported by particular RHEL versions.'
       operationId 'SupportedProfiles'
       content_types
       pagination_params_v2

spec/integration/v2/systems_spec.rb

@@ -14,7 +14,7 @@
     get 'Request Systems' do
       v2_auth_header
       tags 'Systems'
-      description 'Lists Systems'
+      description 'List all systems that are accessible when you are logged into your account.'
       operationId 'Systems'
       content_types
       tags_params
@@ -77,7 +77,7 @@
     get 'Request the list of available OS versions' do
       v2_auth_header
       tags 'Systems'
-      description 'This feature is exclusively used by the frontend'
+      description 'This feature is exclusively used by the frontend.'
       operationId 'SystemsOS'
       content_types
       deprecated true
@@ -99,7 +99,7 @@
     get 'Request a System' do
       v2_auth_header
       tags 'Systems'
-      description 'Returns a System'
+      description 'Get information about one specific system.'
       operationId 'System'
       content_types
 
@@ -149,7 +149,7 @@
     get 'Request Systems assigned to a Policy' do
       v2_auth_header
       tags 'Policies'
-      description 'Lists Systems assigned to a Policy'
+      description 'Retrieve all of the systems assigned to a specific policy.'
       operationId 'PolicySystems'
       content_types
       tags_params
@@ -301,7 +301,7 @@
 
       v2_auth_header
       tags 'Policies'
-      description 'Assigns a System to a Policy'
+      description 'Assign a specific system to a specific policy.'
       operationId 'AssignSystem'
       content_types
 
@@ -340,7 +340,7 @@
 
       v2_auth_header
       tags 'Policies'
-      description 'Unassigns a System from a Policy'
+      description 'Remove a specific system from a specific policy.'
       operationId 'UnassignSystem'
       content_types
 
@@ -392,7 +392,7 @@
     get 'Request Systems assigned to a Report' do
       v2_auth_header
       tags 'Reports'
-      description 'Lists Systems assigned to a Report'
+      description 'Retrieve all of the systems for a specific report.'
       operationId 'ReportSystems'
       content_types
       tags_params
@@ -508,7 +508,7 @@
     get 'Request a System' do
       v2_auth_header
       tags 'Reports'
-      description 'Returns a System under a Report'
+      description 'Retrieve a specific system from a specific report.'
       operationId 'ReportSystem'
       content_types
 

spec/integration/v2/tailorings_spec.rb

@@ -26,7 +26,7 @@
     get 'Request Tailorings' do
       v2_auth_header
       tags 'Policies'
-      description 'Lists Tailorings'
+      description 'Retrieve a list of all tailorings.'
       operationId 'Tailorings'
       content_types
       pagination_params_v2
@@ -139,7 +139,7 @@
     get 'Request a Tailoring' do
       v2_auth_header
       tags 'Policies'
-      description 'Returns a Tailoring'
+      description 'Retrieve a specific tailoring.'
       operationId 'Tailoring'
       content_types
 
@@ -170,7 +170,7 @@
     patch 'Update a Tailoring' do
       v2_auth_header
       tags 'Policies'
-      description 'Updates a Tailoring with the provided value_overrides'
+      description 'Edit or update an existing tailoring.'
       operationId 'UpdateTailoring'
       content_types
 
@@ -212,7 +212,7 @@
     get 'Request the Rule Tree of a Tailoring' do
       v2_auth_header
       tags 'Policies'
-      description 'Returns the Rule Tree of a Tailoring'
+      description 'Returns rule tree of a tailoring.'
       operationId 'TailoringRuleTree'
       content_types
       deprecated true
@@ -260,7 +260,7 @@
     get 'Request a Tailoring file' do
       v2_auth_header
       tags 'Policies'
-      description 'Returns a Tailoring File'
+      description 'Retrieve a tailoring file of a specific tailoring.'
       operationId 'TailoringFile'
       content_types
 

spec/integration/v2/test_results_spec.rb

@@ -34,7 +34,7 @@
     get 'Request Test Results under a Report' do
       v2_auth_header
       tags 'Reports'
-      description 'Lists Test Results under a Report'
+      description 'Retrieve all of the test results for a specific report.'
       operationId 'ReportTestResults'
       content_types
       tags_params
@@ -194,7 +194,7 @@
     get 'Request a Test Result' do
       v2_auth_header
       tags 'Reports'
-      description 'Returns a Test Result under a Report'
+      description 'Retrieve a specific test result for a specific report.'
       operationId 'ReportTestResult'
       content_types