docs(APIv2): RHINENG-14358 spec documentation

RedHatInsights · Nov 22, 2024 · 128ee17 · 128ee17
1 parent be1e9d6
commit 128ee17
Show file tree

Hide file tree

Showing 14 changed files with 85 additions and 84 deletions.
diff --git a/spec/api/v2/openapi.rb b/spec/api/v2/openapi.rb
@@ -46,8 +46,6 @@ 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/]' \

diff --git a/spec/integration/v2/policies_spec.rb b/spec/integration/v2/policies_spec.rb
@@ -14,7 +14,9 @@
     get 'Request Policies' do
       v2_auth_header
       tags 'Policies'
-      description 'Lists Policies'
+      description 'You can see what policies are currently in place.'\
+                  'Policies are statements that manage API scenarios'\
+                  'such as authentication, rate limiting, caching, requests and responses.'
       operationId 'Policies'
       content_types
       pagination_params_v2
@@ -70,7 +72,7 @@
     post 'Create a Policy' do
       v2_auth_header
       tags 'Policies'
-      description 'Create a Policy with the provided attributes'
+      description 'Use this endpoint to create a new security policy.'
       operationId 'CreatePolicy'
       content_types
 
@@ -102,7 +104,7 @@
     get 'Request a Policy' do
       v2_auth_header
       tags 'Policies'
-      description 'Returns a Policy'
+      description 'Use this endpoint to retrieve a specific policy.'
       operationId 'Policy'
       content_types
 
@@ -130,7 +132,7 @@
     patch 'Update a Policy' do
       v2_auth_header
       tags 'Policies'
-      description 'Updates a Policy with the provided attributes'
+      description 'Use this endpoint to edit or update an existing policy.'
       operationId 'UpdatePolicy'
       content_types
 
@@ -152,7 +154,7 @@
     delete 'Delete a Policy' do
       v2_auth_header
       tags 'Policies'
-      description 'Deletes a Policy'
+      description 'Use this endpoint to delete a specific policy.'
       operationId 'DeletePolicy'
       content_types
 
@@ -186,7 +188,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

diff --git a/spec/integration/v2/profiles_spec.rb b/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
 

diff --git a/spec/integration/v2/reports_spec.rb b/spec/integration/v2/reports_spec.rb
@@ -21,7 +21,7 @@
     get 'Request Reports' do
       v2_auth_header
       tags 'Reports'
-      description 'Lists Reports'
+      description 'Use this endpoint to 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 'Use this endpoint to 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 'Use this endpoint to delete test results for a specific report.'
       operationId 'DeleteReport'
       content_types
 

diff --git a/spec/integration/v2/rule_groups_spec.rb b/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
 

diff --git a/spec/integration/v2/rule_results_spec.rb b/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 'Use this endpoint to retrieve all of the rule results for a specific report.'
       operationId 'ReportRuleResults'
       content_types
       pagination_params_v2

diff --git a/spec/integration/v2/rules_spec.rb b/spec/integration/v2/rules_spec.rb
@@ -16,7 +16,7 @@
     get 'Request Rules' do
       v2_auth_header
       tags 'Content'
-      description 'Lists Rules assigned'
+      description 'This is a list of all security guide rules.'
       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.'
       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 'This is 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,8 @@
     get 'Request Rules assigned to a Tailoring' do
       v2_auth_header
       tags 'Policies'
-      description 'Lists Rules assigned to a Tailoring'
+      description 'Use this to get a list of rules relating to specific tailorings. '\
+                  'Tailorings are customizations of rules.'
       operationId 'TailoringRules'
       content_types
       pagination_params_v2
@@ -318,7 +319,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 +356,7 @@
 
       v2_auth_header
       tags 'Policies'
-      description 'Unassigns a Rule from a Tailoring'
+      description 'Customizing of the tailoring by removing rule'
       operationId 'UnassignRule'
       content_types
 

diff --git a/spec/integration/v2/security_guides_spec.rb b/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 'This is a list of all SCAP 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,7 +127,7 @@
     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 the Rule Tree of a Security Guide' # FIXME: Get the security guide rule tree
       operationId 'SecurityGuideRuleTree'
       content_types
 

diff --git a/spec/integration/v2/supported_profiles_spec.rb b/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 'List of profiles supported by certain RHEL versions.'
       operationId 'SupportedProfiles'
       content_types
       pagination_params_v2

diff --git a/spec/integration/v2/systems_spec.rb b/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
@@ -75,7 +75,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
@@ -97,7 +97,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
 
@@ -147,7 +147,7 @@
     get 'Request Systems assigned to a Policy' do
       v2_auth_header
       tags 'Policies'
-      description 'Lists Systems assigned to a Policy'
+      description 'This is a list of all systems assigned to a specific policy.'
       operationId 'PolicySystems'
       content_types
       tags_params
@@ -299,7 +299,7 @@
 
       v2_auth_header
       tags 'Policies'
-      description 'Assigns a System to a Policy'
+      description 'Use this endpoint to connect a specific system to a policy.'
       operationId 'AssignSystem'
       content_types
 
@@ -338,7 +338,7 @@
 
       v2_auth_header
       tags 'Policies'
-      description 'Unassigns a System from a Policy'
+      description 'Use this endpoint to remove the connection between a system and a policy.'
       operationId 'UnassignSystem'
       content_types
 
@@ -390,7 +390,7 @@
     get 'Request Systems assigned to a Report' do
       v2_auth_header
       tags 'Reports'
-      description 'Lists Systems assigned to a Report'
+      description 'Use this endpoint to retrieve all of the systems for a specific report.'
       operationId 'ReportSystems'
       content_types
       tags_params
@@ -506,7 +506,7 @@
     get 'Request a System' do
       v2_auth_header
       tags 'Reports'
-      description 'Returns a System under a Report'
+      description 'Use this endpoint to retrieve a specific system for a specific report.'
       operationId 'ReportSystem'
       content_types
 

diff --git a/spec/integration/v2/tailorings_spec.rb b/spec/integration/v2/tailorings_spec.rb
@@ -26,7 +26,7 @@
     get 'Request Tailorings' do
       v2_auth_header
       tags 'Policies'
-      description 'Lists Tailorings'
+      description 'Use this endpoint to 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 'Use this endpoint to 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 'Use this endpoint to edit or update an existing tailoring.'
       operationId 'UpdateTailoring'
       content_types
 
@@ -260,7 +260,7 @@
     get 'Request a Tailoring file' do
       v2_auth_header
       tags 'Policies'
-      description 'Returns a Tailoring File'
+      description 'Use this endpoint to retrieve a tailoring file of a specific tailoring.'
       operationId 'TailoringFile'
       content_types
 

diff --git a/spec/integration/v2/test_results_spec.rb b/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 'Use this endpoint to 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 'Use this endpoint to retrieve a specific test result for a specific report.'
       operationId 'ReportTestResult'
       content_types
 

diff --git a/spec/integration/v2/value_definitions_spec.rb b/spec/integration/v2/value_definitions_spec.rb
@@ -15,7 +15,7 @@
     get 'Request Value Definitions' do
       v2_auth_header
       tags 'Content'
-      description 'Lists Value Definitions'
+      description 'List the fields that can be edited within your profile.'
       operationId 'ValueDefinitions'
       content_types
       pagination_params_v2
@@ -79,7 +79,7 @@
     get 'Request a Value Definition' do
       v2_auth_header
       tags 'Content'
-      description 'Returns a Value Definition'
+      description 'Retrieve a specific value definition.'
       operationId 'ValueDefinition'
       content_types