Merge "YAML version support"

README.rst

@@ -113,6 +113,14 @@ additional ``--api-ref-src`` argument:
 Your API documentation should now be looking much better. You'll even have
 documentation available inline.
 
+.. note::
+   Beware that the output YAML file follows version 1.2 of the YAML
+   specification and there are libraries, such as PyYAML, that only support
+   version 1.1 and will parse the contents incorrectly.
+
+   Option ``--yaml-version 1.1`` can be passed on the call to force the output
+   to use specification version 1.1.
+
 There are a variety of options available, which you can view with the
 ``--help`` option.
 

codegenerator/cli.py

@@ -167,6 +167,18 @@ def main():
         ],
         help="Target for which to generate code",
     )
+    parser.add_argument(
+        "--yaml-version",
+        choices=["1.1", "1.2"],
+        default="",
+        help=(
+            "Yaml specification version to use for openapi-spec target "
+            "output. Defaults to latest supported version without the YAML "
+            "directive, which will be included if version is explicit (eg: "
+            "%%YAML 1.2). Beware of libraries like PyYaml that only support "
+            "version 1.1"
+        ),
+    )
     parser.add_argument(
         "--work-dir", help="Working directory for the generated code"
     )

codegenerator/openapi/barbican.py

@@ -493,7 +493,11 @@ class BarbicanGenerator(OpenStackServerSourceBase):
             )
 
         self.dump_openapi(
-            openapi_spec, Path(impl_path), args.validate, "key-manager"
+            openapi_spec,
+            Path(impl_path),
+            args.validate,
+            "key-manager",
+            args.yaml_version,
         )
 
         lnk = Path(impl_path.parent, "v1.yaml")

codegenerator/openapi/base.py

@@ -191,12 +191,21 @@ class OpenStackServerSourceBase:
         if spec:
             return SpecSchema(**spec)
 
-    def dump_openapi(self, spec, path, validate: bool, service_type: str):
+    def dump_openapi(
+        self,
+        spec,
+        path,
+        validate: bool,
+        service_type: str,
+        yaml_version: str = "",
+    ):
         """Dump OpenAPI spec into the file"""
         if validate:
             self.validate_spec(spec, service_type)
         yaml = YAML()
         yaml.preserve_quotes = True
+        if yaml_version:
+            yaml.version = yaml_version
         yaml.indent(mapping=2, sequence=4, offset=2)
         with open(path, "w") as fp:
             yaml.dump(

codegenerator/openapi/cinder.py

@@ -183,7 +183,11 @@ class CinderV3Generator(OpenStackServerSourceBase):
             merge_api_ref_doc(openapi_spec, args.api_ref_src)
 
         self.dump_openapi(
-            openapi_spec, impl_path, args.validate, "block-storage"
+            openapi_spec,
+            impl_path,
+            args.validate,
+            "block-storage",
+            args.yaml_version,
         )
 
         lnk = Path(impl_path.parent, "v3.yaml")

codegenerator/openapi/designate.py

@@ -250,7 +250,13 @@ class DesignateGenerator(OpenStackServerSourceBase):
                 openapi_spec, args.api_ref_src, allow_strip_version=False
             )
 
-        self.dump_openapi(openapi_spec, Path(impl_path), args.validate, "dns")
+        self.dump_openapi(
+            openapi_spec,
+            Path(impl_path),
+            args.validate,
+            "dns",
+            args.yaml_version,
+        )
 
         lnk = Path(impl_path.parent, "v2.yaml")
         lnk.unlink(missing_ok=True)

codegenerator/openapi/glance.py

@@ -333,7 +333,9 @@ class GlanceGenerator(OpenStackServerSourceBase):
         if args.api_ref_src:
             merge_api_ref_doc(openapi_spec, args.api_ref_src)
 
-        self.dump_openapi(openapi_spec, impl_path, args.validate, "image")
+        self.dump_openapi(
+            openapi_spec, impl_path, args.validate, "image", args.yaml_version
+        )
 
         lnk = Path(impl_path.parent, "v2.yaml")
         lnk.unlink(missing_ok=True)

codegenerator/openapi/ironic.py

@@ -193,7 +193,11 @@ class IronicGenerator(OpenStackServerSourceBase):
             )
 
         self.dump_openapi(
-            openapi_spec, Path(impl_path), args.validate, "baremetal"
+            openapi_spec,
+            Path(impl_path),
+            args.validate,
+            "baremetal",
+            args.yaml_version,
         )
 
         lnk = Path(impl_path.parent, "v1.yaml")

codegenerator/openapi/keystone.py

@@ -162,7 +162,13 @@ class KeystoneGenerator(OpenStackServerSourceBase):
                 openapi_spec, args.api_ref_src, allow_strip_version=False
             )
 
-        self.dump_openapi(openapi_spec, impl_path, args.validate, "identity")
+        self.dump_openapi(
+            openapi_spec,
+            impl_path,
+            args.validate,
+            "identity",
+            args.yaml_version,
+        )
 
         lnk = Path(impl_path.parent, "v3.yaml")
         lnk.unlink(missing_ok=True)

codegenerator/openapi/magnum.py

@@ -237,6 +237,7 @@ class MagnumGenerator(OpenStackServerSourceBase):
             Path(impl_path),
             args.validate,
             "container-infrastructure-management",
+            args.yaml_version,
         )
 
         lnk = Path(impl_path.parent, "v1.yaml")

codegenerator/openapi/manila.py

@@ -123,7 +123,11 @@ class ManilaGenerator(OpenStackServerSourceBase):
             )
 
         self.dump_openapi(
-            openapi_spec, impl_path, args.validate, "shared-file-system"
+            openapi_spec,
+            impl_path,
+            args.validate,
+            "shared-file-system",
+            args.yaml_version,
         )
 
         lnk = Path(impl_path.parent, "v2.yaml")

codegenerator/openapi/neutron.py

@@ -180,7 +180,13 @@ class NeutronGenerator(OpenStackServerSourceBase):
         # Add base resource routes exposed as a pecan app
         self._process_base_resource_routes(openapi_spec, processed_routes)
 
-        self.dump_openapi(openapi_spec, impl_path, args.validate, "network")
+        self.dump_openapi(
+            openapi_spec,
+            impl_path,
+            args.validate,
+            "network",
+            args.yaml_version,
+        )
 
     def process_neutron_with_vpnaas(self, work_dir, processed_routes, args):
         """Setup base Neutron with enabled vpnaas"""
@@ -240,7 +246,13 @@ class NeutronGenerator(OpenStackServerSourceBase):
 
         (impl_path, openapi_spec) = self._read_spec(work_dir)
         self._process_router(router, openapi_spec, processed_routes)
-        self.dump_openapi(openapi_spec, impl_path, args.validate, "network")
+        self.dump_openapi(
+            openapi_spec,
+            impl_path,
+            args.validate,
+            "network",
+            args.yaml_version,
+        )
 
     def _read_spec(self, work_dir):
         """Read the spec from file or create an empty one"""
@@ -374,7 +386,11 @@ class NeutronGenerator(OpenStackServerSourceBase):
             )
 
         self.dump_openapi(
-            openapi_spec, Path(impl_path), args.validate, "network"
+            openapi_spec,
+            Path(impl_path),
+            args.validate,
+            "network",
+            args.yaml_version,
         )
 
         return impl_path

codegenerator/openapi/nova.py

@@ -112,7 +112,13 @@ class NovaGenerator(OpenStackServerSourceBase):
                 doc_url_prefix="/v2.1",
             )
 
-        self.dump_openapi(openapi_spec, impl_path, args.validate, "compute")
+        self.dump_openapi(
+            openapi_spec,
+            impl_path,
+            args.validate,
+            "compute",
+            args.yaml_version,
+        )
 
         lnk = Path(impl_path.parent, "v2.yaml")
         lnk.unlink(missing_ok=True)

codegenerator/openapi/octavia.py

@@ -1092,7 +1092,11 @@ class OctaviaGenerator(OpenStackServerSourceBase):
             )
 
         self.dump_openapi(
-            openapi_spec, Path(impl_path), args.validate, "load-balancer"
+            openapi_spec,
+            Path(impl_path),
+            args.validate,
+            "load-balancer",
+            args.yaml_version,
         )
 
         lnk = Path(impl_path.parent, "v2.yaml")

codegenerator/openapi/placement.py

@@ -121,7 +121,13 @@ class PlacementGenerator(OpenStackServerSourceBase):
                 openapi_spec, args.api_ref_src, allow_strip_version=False
             )
 
-        self.dump_openapi(openapi_spec, impl_path, args.validate, "placement")
+        self.dump_openapi(
+            openapi_spec,
+            impl_path,
+            args.validate,
+            "placement",
+            args.yaml_version,
+        )
 
         lnk = Path(impl_path.parent, "v1.yaml")
         lnk.unlink(missing_ok=True)