phoenix-oss/llama-stack-mirror
0
0
Fork 1
mirror of https://github.com/meta-llama/llama-stack.git synced 2025-12-11 19:56:03 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

chore: use JSON instead of YAML for openapi generation

Browse source 
JSON has a few advantages over YAML in this context:

* No extra dependency: Removed ruamel.yaml; using the standard library
  json module.
* Simpler code: No YAML formatting configuration (indent, flow style,
  string presentation, etc.). JSON serialization is straightforward.
* Faster generation: JSON serialization is typically faster and more
  predictable than YAML formatting.
* Native OpenAPI format: JSON is the native OpenAPI format. Many tools
  prefer JSON, reducing potential compatibility issues.
* Better tooling support: JSON is widely supported. Tools like oasdiff,
  OpenAPI validators, and code generators work well with JSON.
* Fewer formatting edge cases: YAML can have edge cases (multiline
  strings, special characters, quoting, scalars etc). JSON avoids these.

All the tools consumming the YAMLs have been updated namely oasdiff for
conformance tests, docusaurus config and the genrator.

Signed-off-by: Sébastien Han <seb@redhat.com>
This commit is contained in:
Sébastien Han 2025-11-03 11:54:50 +01:00
parent d4aa348b60
commit 44e36ce48d
No known key found for this signature in database
15 changed files with 71155 additions and 29137 deletions
Download patch file Download diff file Expand all files Collapse all files

36
docs/openapi_generator/generate.py
View file

@ -14,7 +14,6 @@ from datetime import datetime
from pathlib import Path
import sys
import fire
import ruamel.yaml as yaml
from llama_stack.apis.version import LLAMA_STACK_API_V1 # noqa: E402
from llama_stack.core.stack import LlamaStack # noqa: E402
@ -24,16 +23,6 @@ from .pyopenapi.specification import Info, Server # noqa: E402
from .pyopenapi.utility import Specification, validate_api # noqa: E402
def str_presenter(dumper, data):
if data.startswith(f"/{LLAMA_STACK_API_V1}") or data.startswith(
"#/components/schemas/"
):
style = None
else:
style = ">" if "\n" in data or len(data) > 40 else None
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, combined_spec: bool = False):
"""Generate OpenAPI spec with optional stability filtering."""
@ -83,23 +72,14 @@ def generate_spec(output_dir: Path, stability_filter: str = None, main_spec: boo
),
)
yaml_filename = f"{filename_prefix}llama-stack-spec.yaml"
json_filename = f"{filename_prefix}llama-stack-spec.json"
with open(output_dir / yaml_filename, "w", encoding="utf-8") as fp:
y = yaml.YAML()
y.default_flow_style = False
y.block_seq_indent = 2
y.map_indent = 2
y.sequence_indent = 4
y.sequence_dash_offset = 2
y.width = 80
y.allow_unicode = True
y.representer.add_representer(str, str_presenter)
with open(output_dir / json_filename, "w", encoding="utf-8") as fp:
spec.write_json(fp, pretty_print=True)
# add a newline to the end of the file
fp.write("\n")
y.dump(
spec.get_json(),
fp,
)
print(f"Generated {json_filename}")
def main(output_dir: str):
output_dir = Path(output_dir)
@ -115,10 +95,10 @@ def main(output_dir: str):
sys.exit(1)
now = str(datetime.now())
print(f"Converting the spec to YAML (openapi.yaml) and HTML (openapi.html) at {now}")
print(f"Converting the spec to JSON (openapi.json) and HTML (openapi.html) at {now}")
print("")
# Generate main spec as stable APIs (llama-stack-spec.yaml)
# Generate main spec as stable APIs (llama-stack-spec.json)
print("Generating main specification (stable APIs)...")
generate_spec(output_dir, "stable", main_spec=True)