feat: resolve comments to CLI experience

src/apic-extension/azext_apic_extension/_help.py

@@ -12,7 +12,7 @@
 
 helps['apic api register'] = """
     type: command
-    short-summary: Single Command for registering api, api version, api definition, import spec, create deployment provided a spec file.
+    short-summary: Registers a new API with version, definition, and associated deployments using the specification file as the source of truth.
     parameters:
       - name: --api-location -l
         type: string

src/apic-extension/azext_apic_extension/aaz/latest/apic/api/__init__.py

@@ -9,9 +9,9 @@
 # flake8: noqa
 
 from .__cmd_group import *
+from ._check_exists import *
 from ._create import *
 from ._delete import *
-from ._head import *
 from ._list import *
 from ._show import *
 from ._update import *

src/apic-extension/azext_apic_extension/aaz/latest/apic/api/_head.py → src/apic-extension/azext_apic_extension/aaz/latest/apic/api/_check_exists.py

@@ -12,9 +12,9 @@
 
 
 @register_command(
-    "apic api head",
+    "apic api check-exists",
 )
-class Head(AAZCommand):
+class CheckExists(AAZCommand):
     """Checks if specified API exists.
     """
 
@@ -41,9 +41,9 @@ def _build_arguments_schema(cls, *args, **kwargs):
         # define Arg Group ""
 
         _args_schema = cls._args_schema
-        _args_schema.api_name = AAZStrArg(
-            options=["--api", "--name", "--api-name"],
-            help="The name of the API.",
+        _args_schema.api_id = AAZStrArg(
+            options=["--api-id"],
+            help="The id of the API.",
             required=True,
             id_part="child_name_2",
             fmt=AAZStrArgFormat(
@@ -120,7 +120,7 @@ def error_format(self):
         def url_parameters(self):
             parameters = {
                 **self.serialize_url_param(
-                    "apiName", self.ctx.args.api_name,
+                    "apiName", self.ctx.args.api_id,
                     required=True,
                 ),
                 **self.serialize_url_param(
@@ -156,8 +156,8 @@ def on_200(self, session):
             pass
 
 
-class _HeadHelper:
-    """Helper class for Head"""
+class _CheckExistsHelper:
+    """Helper class for CheckExists"""
 
 
-__all__ = ["Head"]
+__all__ = ["CheckExists"]

src/apic-extension/azext_apic_extension/aaz/latest/apic/api/_create.py

@@ -15,10 +15,10 @@
     "apic api create",
 )
 class Create(AAZCommand):
-    """Create new or updates existing API.
+    """Register a new API.
 
     :example: Create API
-        az apic api create -g contoso-resources -s contoso --name echo-api --title "Echo API"
+        az apic api create -g contoso-resources -s contoso --api-id echo-api --title "Echo API" --type REST
     """
 
     _aaz_info = {
@@ -44,9 +44,9 @@ def _build_arguments_schema(cls, *args, **kwargs):
         # define Arg Group ""
 
         _args_schema = cls._args_schema
-        _args_schema.api_name = AAZStrArg(
-            options=["--api", "--name", "--api-name"],
-            help="The name of the API.",
+        _args_schema.api_id = AAZStrArg(
+            options=["--api-id"],
+            help="The id of the API.",
             required=True,
             fmt=AAZStrArgFormat(
                 max_length=90,
@@ -103,11 +103,11 @@ def _build_arguments_schema(cls, *args, **kwargs):
             arg_group="Properties",
             help="Additional, external documentation for the API.",
         )
-        _args_schema.kind = AAZStrArg(
-            options=["--kind"],
+        _args_schema.type = AAZStrArg(
+            options=["--type"],
             arg_group="Properties",
-            help="Kind of API. For example, REST or GraphQL.",
             required=True,
+            help="Type of API.",
             enum={"graphql": "graphql", "grpc": "grpc", "rest": "rest", "soap": "soap", "webhook": "webhook", "websocket": "websocket"},
         )
         _args_schema.license = AAZObjectArg(
@@ -273,7 +273,7 @@ def error_format(self):
         def url_parameters(self):
             parameters = {
                 **self.serialize_url_param(
-                    "apiName", self.ctx.args.api_name,
+                    "apiName", self.ctx.args.api_id,
                     required=True,
                 ),
                 **self.serialize_url_param(
@@ -332,7 +332,7 @@ def content(self):
                 properties.set_prop("customProperties", AAZFreeFormDictType, ".custom_properties")
                 properties.set_prop("description", AAZStrType, ".description")
                 properties.set_prop("externalDocumentation", AAZListType, ".external_documentation")
-                properties.set_prop("kind", AAZStrType, ".kind", typ_kwargs={"flags": {"required": True}})
+                properties.set_prop("kind", AAZStrType, ".type", typ_kwargs={"flags": {"required": True}})
                 properties.set_prop("license", AAZObjectType, ".license")
                 properties.set_prop("summary", AAZStrType, ".summary")
                 properties.set_prop("termsOfService", AAZObjectType, ".terms_of_service")
@@ -424,6 +424,7 @@ def _build_schema_on_200_201(cls):
             properties.license = AAZObjectType()
             properties.lifecycle_stage = AAZStrType(
                 serialized_name="lifecycleStage",
+                flags={"read_only": True},
             )
             properties.summary = AAZStrType()
             properties.terms_of_service = AAZObjectType(

src/apic-extension/azext_apic_extension/aaz/latest/apic/api/_delete.py

@@ -19,7 +19,7 @@ class Delete(AAZCommand):
     """Delete specified API.
 
     :example: Delete API
-        az apic api delete -g contoso-resources -s contoso --name echo-api
+        az apic api delete -g contoso-resources -s contoso --api-id echo-api
     """
 
     _aaz_info = {
@@ -45,9 +45,9 @@ def _build_arguments_schema(cls, *args, **kwargs):
         # define Arg Group ""
 
         _args_schema = cls._args_schema
-        _args_schema.api_name = AAZStrArg(
-            options=["--api", "--name", "--api-name"],
-            help="The name of the API.",
+        _args_schema.api_id = AAZStrArg(
+            options=["--api-id"],
+            help="The id of the API.",
             required=True,
             id_part="child_name_2",
             fmt=AAZStrArgFormat(
@@ -126,7 +126,7 @@ def error_format(self):
         def url_parameters(self):
             parameters = {
                 **self.serialize_url_param(
-                    "apiName", self.ctx.args.api_name,
+                    "apiName", self.ctx.args.api_id,
                     required=True,
                 ),
                 **self.serialize_url_param(

src/apic-extension/azext_apic_extension/aaz/latest/apic/api/_list.py

@@ -223,6 +223,7 @@ def _build_schema_on_200(cls):
             properties.license = AAZObjectType()
             properties.lifecycle_stage = AAZStrType(
                 serialized_name="lifecycleStage",
+                flags={"read_only": True},
             )
             properties.summary = AAZStrType()
             properties.terms_of_service = AAZObjectType(

src/apic-extension/azext_apic_extension/aaz/latest/apic/api/_show.py

@@ -18,7 +18,7 @@ class Show(AAZCommand):
     """Get details of the API.
 
     :example: Show API details
-        az apic api show -g contoso-resources -s contoso --name echo-api
+        az apic api show -g contoso-resources -s contoso --api-id echo-api
     """
 
     _aaz_info = {
@@ -44,9 +44,9 @@ def _build_arguments_schema(cls, *args, **kwargs):
         # define Arg Group ""
 
         _args_schema = cls._args_schema
-        _args_schema.api_name = AAZStrArg(
-            options=["--api", "--name", "--api-name"],
-            help="The name of the API.",
+        _args_schema.api_id = AAZStrArg(
+            options=["--api-id"],
+            help="The id of the API.",
             required=True,
             id_part="child_name_2",
             fmt=AAZStrArgFormat(
@@ -127,7 +127,7 @@ def error_format(self):
         def url_parameters(self):
             parameters = {
                 **self.serialize_url_param(
-                    "apiName", self.ctx.args.api_name,
+                    "apiName", self.ctx.args.api_id,
                     required=True,
                 ),
                 **self.serialize_url_param(
@@ -218,6 +218,7 @@ def _build_schema_on_200(cls):
             properties.license = AAZObjectType()
             properties.lifecycle_stage = AAZStrType(
                 serialized_name="lifecycleStage",
+                flags={"read_only": True},
             )
             properties.summary = AAZStrType()
             properties.terms_of_service = AAZObjectType(

src/apic-extension/azext_apic_extension/aaz/latest/apic/api/_update.py

@@ -15,10 +15,10 @@
     "apic api update",
 )
 class Update(AAZCommand):
-    """Update new or updates existing API.
+    """Update existing API.
 
     :example: Update API
-        az apic api update -g contoso-resources -s contoso --name echo-api --summary "Basic REST API service"
+        az apic api update -g contoso-resources -s contoso --api-id echo-api --summary "Basic REST API service"
     """
 
     _aaz_info = {
@@ -46,9 +46,9 @@ def _build_arguments_schema(cls, *args, **kwargs):
         # define Arg Group ""
 
         _args_schema = cls._args_schema
-        _args_schema.api_name = AAZStrArg(
-            options=["--api", "--name", "--api-name"],
-            help="The name of the API.",
+        _args_schema.api_id = AAZStrArg(
+            options=["--api-id"],
+            help="The id of the API.",
             required=True,
             id_part="child_name_2",
             fmt=AAZStrArgFormat(
@@ -111,10 +111,10 @@ def _build_arguments_schema(cls, *args, **kwargs):
             help="Additional, external documentation for the API.",
             nullable=True,
         )
-        _args_schema.kind = AAZStrArg(
-            options=["--kind"],
+        _args_schema.type = AAZStrArg(
+            options=["--type"],
             arg_group="Properties",
-            help="Kind of API. For example, REST or GraphQL.",
+            help="Type of API.",
             enum={"graphql": "graphql", "grpc": "grpc", "rest": "rest", "soap": "soap", "webhook": "webhook", "websocket": "websocket"},
         )
         _args_schema.license = AAZObjectArg(
@@ -305,7 +305,7 @@ def error_format(self):
         def url_parameters(self):
             parameters = {
                 **self.serialize_url_param(
-                    "apiName", self.ctx.args.api_name,
+                    "apiName", self.ctx.args.api_id,
                     required=True,
                 ),
                 **self.serialize_url_param(
@@ -396,7 +396,7 @@ def error_format(self):
         def url_parameters(self):
             parameters = {
                 **self.serialize_url_param(
-                    "apiName", self.ctx.args.api_name,
+                    "apiName", self.ctx.args.api_id,
                     required=True,
                 ),
                 **self.serialize_url_param(
@@ -488,7 +488,7 @@ def _update_instance(self, instance):
                 properties.set_prop("customProperties", AAZFreeFormDictType, ".custom_properties")
                 properties.set_prop("description", AAZStrType, ".description")
                 properties.set_prop("externalDocumentation", AAZListType, ".external_documentation")
-                properties.set_prop("kind", AAZStrType, ".kind", typ_kwargs={"flags": {"required": True}})
+                properties.set_prop("kind", AAZStrType, ".type", typ_kwargs={"flags": {"required": True}})
                 properties.set_prop("license", AAZObjectType, ".license")
                 properties.set_prop("summary", AAZStrType, ".summary")
                 properties.set_prop("termsOfService", AAZObjectType, ".terms_of_service")
@@ -589,6 +589,7 @@ def _build_schema_api_read(cls, _schema):
         properties.license = AAZObjectType()
         properties.lifecycle_stage = AAZStrType(
             serialized_name="lifecycleStage",
+            flags={"read_only": True},
         )
         properties.summary = AAZStrType()
         properties.terms_of_service = AAZObjectType(

src/apic-extension/azext_apic_extension/aaz/latest/apic/api/definition/__cmd_group.py

@@ -15,7 +15,7 @@
     "apic api definition",
 )
 class __CMDGroup(AAZCommandGroup):
-    """Commands to manage API Definitions in API Center
+    """Commands to manage API definitions in API Center
     """
     pass
 

src/apic-extension/azext_apic_extension/aaz/latest/apic/api/definition/__init__.py

@@ -9,10 +9,10 @@
 # flake8: noqa
 
 from .__cmd_group import *
+from ._check_exists import *
 from ._create import *
 from ._delete import *
 from ._export_specification import *
-from ._head import *
 from ._import_specification import *
 from ._list import *
 from ._show import *

src/apic-extension/azext_apic_extension/aaz/latest/apic/api/definition/_head.py → src/apic-extension/azext_apic_extension/aaz/latest/apic/api/definition/_check_exists.py

@@ -12,9 +12,9 @@
 
 
 @register_command(
-    "apic api definition head",
+    "apic api definition check-exists",
 )
-class Head(AAZCommand):
+class CheckExists(AAZCommand):
     """Checks if specified API definition exists.
     """
 
@@ -41,19 +41,19 @@ def _build_arguments_schema(cls, *args, **kwargs):
         # define Arg Group ""
 
         _args_schema = cls._args_schema
-        _args_schema.api_name = AAZStrArg(
-            options=["--api", "--api-name"],
-            help="The name of the API.",
+        _args_schema.api_id = AAZStrArg(
+            options=["--api-id"],
+            help="The id of the API.",
             required=True,
             id_part="child_name_2",
             fmt=AAZStrArgFormat(
                 max_length=90,
                 min_length=1,
             ),
         )
-        _args_schema.definition_name = AAZStrArg(
-            options=["--name", "--definition", "--definition-name"],
-            help="The name of the API definition.",
+        _args_schema.definition_id = AAZStrArg(
+            options=["--definition-id"],
+            help="The id of the API definition.",
             required=True,
             id_part="child_name_4",
             fmt=AAZStrArgFormat(
@@ -74,9 +74,9 @@ def _build_arguments_schema(cls, *args, **kwargs):
                 min_length=1,
             ),
         )
-        _args_schema.version_name = AAZStrArg(
-            options=["--version", "--version-name"],
-            help="The name of the API version.",
+        _args_schema.version_id = AAZStrArg(
+            options=["--version-id"],
+            help="The id of the API version.",
             required=True,
             id_part="child_name_3",
             fmt=AAZStrArgFormat(
@@ -140,11 +140,11 @@ def error_format(self):
         def url_parameters(self):
             parameters = {
                 **self.serialize_url_param(
-                    "apiName", self.ctx.args.api_name,
+                    "apiName", self.ctx.args.api_id,
                     required=True,
                 ),
                 **self.serialize_url_param(
-                    "definitionName", self.ctx.args.definition_name,
+                    "definitionName", self.ctx.args.definition_id,
                     required=True,
                 ),
                 **self.serialize_url_param(
@@ -160,7 +160,7 @@ def url_parameters(self):
                     required=True,
                 ),
                 **self.serialize_url_param(
-                    "versionName", self.ctx.args.version_name,
+                    "versionName", self.ctx.args.version_id,
                     required=True,
                 ),
                 **self.serialize_url_param(
@@ -184,8 +184,8 @@ def on_200(self, session):
             pass
 
 
-class _HeadHelper:
-    """Helper class for Head"""
+class _CheckExistsHelper:
+    """Helper class for CheckExists"""
 
 
-__all__ = ["Head"]
+__all__ = ["CheckExists"]