mirror of
https://github.com/meta-llama/llama-stack.git
synced 2025-10-04 04:04:14 +00:00
b6a5bccadf
# What does this PR do? First step towards cleaning up the API reference section of the docs. - Separates API reference into 3 sections: stable (`v1`), experimental (`v1alpha` and `v1beta`), and deprecated (`deprecated=True`) - Each section is accessible via the dropdown menu and `docs/api-overview` <img width="1237" height="321" alt="Screenshot 2025-09-30 at 5 47 30 PM" src="https://github.com/user-attachments/assets/fe0e498c-b066-46ed-a48e-4739d3b6724c" /> <img width="860" height="510" alt="Screenshot 2025-09-30 at 5 47 49 PM" src="https://github.com/user-attachments/assets/a92a8d8c-94bf-42d5-9f5b-b47bb2b14f9c" /> - Deprecated APIs: Added styling to the sidebar, and a notice on the endpoint pages <img width="867" height="428" alt="Screenshot 2025-09-30 at 5 47 43 PM" src="https://github.com/user-attachments/assets/9e6e050d-c782-461b-8084-5ff6496d7bd9" /> Closes #3628 TODO in follow-up PRs: - Add the ability to annotate API groups with supplementary content (so we can have longer descriptions of complex APIs like Responses) - Clean up docstrings to show API endpoints (or short semantic titles) in the sidebar ## Test Plan - Local testing - Made sure API conformance test still passes
78 lines
3 KiB
Python
78 lines
3 KiB
Python
# Copyright (c) Meta Platforms, Inc. and affiliates.
|
|
# All rights reserved.
|
|
#
|
|
# This source code is licensed under the terms described in the LICENSE file in
|
|
# the root directory of this source tree.
|
|
|
|
import dataclasses
|
|
from dataclasses import dataclass
|
|
from http import HTTPStatus
|
|
from typing import Callable, ClassVar, Dict, List, Optional, Tuple, Union
|
|
|
|
from .specification import (
|
|
Info,
|
|
SecurityScheme,
|
|
SecuritySchemeAPI,
|
|
SecuritySchemeHTTP,
|
|
SecuritySchemeOpenIDConnect,
|
|
Server,
|
|
)
|
|
|
|
HTTPStatusCode = Union[HTTPStatus, int, str]
|
|
|
|
|
|
@dataclass
|
|
class Options:
|
|
"""
|
|
:param server: Base URL for the API endpoint.
|
|
:param info: Meta-information for the endpoint specification.
|
|
:param version: OpenAPI specification version as a tuple of major, minor, revision.
|
|
:param default_security_scheme: Security scheme to apply to endpoints, unless overridden on a per-endpoint basis.
|
|
:param extra_types: Extra types in addition to those found in operation signatures. Use a dictionary to group related types.
|
|
:param use_examples: Whether to emit examples for operations.
|
|
:param success_responses: Associates operation response types with HTTP status codes.
|
|
:param error_responses: Associates error response types with HTTP status codes.
|
|
:param error_wrapper: True if errors are encapsulated in an error object wrapper.
|
|
:param property_description_fun: Custom transformation function to apply to class property documentation strings.
|
|
:param captions: User-defined captions for sections such as "Operations" or "Types", and (if applicable) groups of extra types.
|
|
:param include_standard_error_responses: Whether to include standard error responses (400, 429, 500, 503) in all operations.
|
|
"""
|
|
|
|
server: Server
|
|
info: Info
|
|
version: Tuple[int, int, int] = (3, 1, 0)
|
|
default_security_scheme: Optional[SecurityScheme] = None
|
|
extra_types: Union[List[type], Dict[str, List[type]], None] = None
|
|
use_examples: bool = True
|
|
success_responses: Dict[type, HTTPStatusCode] = dataclasses.field(
|
|
default_factory=dict
|
|
)
|
|
error_responses: Dict[type, HTTPStatusCode] = dataclasses.field(
|
|
default_factory=dict
|
|
)
|
|
error_wrapper: bool = False
|
|
property_description_fun: Optional[Callable[[type, str, str], str]] = None
|
|
captions: Optional[Dict[str, str]] = None
|
|
include_standard_error_responses: bool = True
|
|
stability_filter: Optional[str] = None
|
|
|
|
default_captions: ClassVar[Dict[str, str]] = {
|
|
"Operations": "Operations",
|
|
"Types": "Types",
|
|
"Events": "Events",
|
|
"AdditionalTypes": "Additional types",
|
|
}
|
|
|
|
def map(self, id: str) -> str:
|
|
"Maps a language-neutral placeholder string to language-dependent text."
|
|
|
|
if self.captions is not None:
|
|
caption = self.captions.get(id)
|
|
if caption is not None:
|
|
return caption
|
|
|
|
caption = self.__class__.default_captions.get(id)
|
|
if caption is not None:
|
|
return caption
|
|
|
|
raise KeyError(f"no caption found for ID: {id}")
|