docs: API spec generation for Stainless

docs/openapi_generator/generate.py

@@ -34,10 +34,17 @@ def str_presenter(dumper, data):
     return dumper.represent_scalar("tag:yaml.org,2002:str", data, style=style)
 
 
-def generate_spec(output_dir: Path, stability_filter: str = None, main_spec: bool = False):
+def generate_spec(output_dir: Path, stability_filter: str = None, main_spec: bool = False, combined_spec: bool = False):
     """Generate OpenAPI spec with optional stability filtering."""
 
-    if stability_filter:
+    if combined_spec:
+        # Special case for combined stable + experimental APIs
+        title_suffix = " - Stable & Experimental APIs"
+        filename_prefix = "stainless-"
+        description_suffix = "\n\n**🔗 COMBINED**: This specification includes both stable production-ready APIs and experimental pre-release APIs. Use stable APIs for production deployments and experimental APIs for testing new features."
+        # Use the special "stainless" filter to include stable + experimental APIs
+        stability_filter = "stainless"
+    elif stability_filter:
         title_suffix = {
             "stable": " - Stable APIs" if not main_spec else "",
             "experimental": " - Experimental APIs",
@@ -125,6 +132,9 @@ def main(output_dir: str):
     generate_spec(output_dir, "experimental")
     generate_spec(output_dir, "deprecated")
 
+    print("Generating combined stable + experimental specification...")
+    generate_spec(output_dir, combined_spec=True)
+
 
 if __name__ == "__main__":
     fire.Fire(main)

docs/openapi_generator/pyopenapi/generator.py

@@ -948,6 +948,10 @@ class Generator:
                     # Include only deprecated endpoints
                     if deprecated:
                         filtered_operations.append(op)
+                elif self.options.stability_filter == "stainless":
+                    # Include both stable (v1 non-deprecated) and experimental (v1alpha, v1beta) endpoints
+                    if (stability_level == "v1" and not deprecated) or stability_level in ["v1alpha", "v1beta"]:
+                        filtered_operations.append(op)
 
             operations = filtered_operations
             print(