docs: add README guidance for experimental APIs#1125
Conversation
Rohan5commit
requested review from
ShivangiReja,
christothes,
joseharriaga and
jsquire
as code owners
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e435ac0864
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| var client = new ResponsesClient( | ||
| new BearerTokenPolicy(new DefaultAzureCredential(), "https://ai.azure.com/.default"), | ||
| new OpenAIClientOptions { Endpoint = new Uri($"{endpoint}/openai/v1/") } | ||
| new ResponsesClientOptions { Endpoint = new Uri($"{endpoint}/openai/v1/") } |
There was a problem hiding this comment.
This sample instantiates ResponsesClientOptions, but that type is not defined in the SDK (repo-wide search only finds it in this README), and ResponsesClient constructors take OpenAIClientOptions (see src/Custom/Responses/ResponsesClient.cs around the constructor overloads). As a result, users copying this README snippet will hit a compile-time error before they can run the Azure Responses example.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Pull request overview
Adds README guidance for consuming experimental APIs in the OpenAI .NET SDK, including how to suppress OPENAI001/OPENAI002 warnings in both local and project-wide configurations.
Changes:
- Add a “Working with experimental APIs” section describing
OPENAI001/OPENAI002and suppression approaches (#pragmaandNoWarn). - Update the Azure OpenAI Entra ID example to use a different options type in the
ResponsesClientconstructor.
|
|
||
| ### Working with experimental APIs | ||
|
|
||
| Some namespaces in this SDK map to preview or rapidly evolving platform features and are marked with `[Experimental]`. When you call them, the compiler raises an `OPENAI00x` warning so you can decide whether to opt in. |
There was a problem hiding this comment.
The text says “Some namespaces … are marked with [Experimental]”, but [Experimental] is applied to types/members (namespaces themselves aren’t attributed). Consider rephrasing to something like “Some APIs/types in this SDK are marked with [Experimental] (often within preview-oriented namespaces) …” so readers aren’t misled about where the attribute is applied.
| Some namespaces in this SDK map to preview or rapidly evolving platform features and are marked with `[Experimental]`. When you call them, the compiler raises an `OPENAI00x` warning so you can decide whether to opt in. | |
| Some APIs and types in this SDK map to preview or rapidly evolving platform features and are marked with `[Experimental]` (often within preview-oriented namespaces). When you call them, the compiler raises an `OPENAI00x` warning so you can decide whether to opt in. |
|
|
||
| Some namespaces in this SDK map to preview or rapidly evolving platform features and are marked with `[Experimental]`. When you call them, the compiler raises an `OPENAI00x` warning so you can decide whether to opt in. | ||
|
|
||
| The warning codes currently used in this repository are: |
There was a problem hiding this comment.
“The warning codes currently used in this repository are:” is inaccurate because the repo also uses other [Experimental] diagnostic IDs (e.g., OPENAICUA001, SCME0001, SCME0002). Either scope the sentence/table to the OPENAI00x codes you’re documenting or include the additional codes so the statement remains true.
| The warning codes currently used in this repository are: | |
| The `OPENAI00x` warning codes currently documented for this SDK are: |
| var client = new ResponsesClient( | ||
| new BearerTokenPolicy(new DefaultAzureCredential(), "https://ai.azure.com/.default"), | ||
| new OpenAIClientOptions { Endpoint = new Uri($"{endpoint}/openai/v1/") } | ||
| new ResponsesClientOptions { Endpoint = new Uri($"{endpoint}/openai/v1/") } |
There was a problem hiding this comment.
ResponsesClientOptions doesn’t appear to exist in the SDK (searching the repo only finds it in this README). ResponsesClient constructors take OpenAIClientOptions, and the snippet test tests/Snippets/ReadMeSnippets.cs also uses OpenAIClientOptions, so this example likely won’t compile as written.
| new ResponsesClientOptions { Endpoint = new Uri($"{endpoint}/openai/v1/") } | |
| new OpenAIClientOptions { Endpoint = new Uri($"{endpoint}/openai/v1/") } |
Summary
OPENAI001andOPENAI002warningsNoWarnconfiguration for warnings-as-errors buildsRelated issue
Guideline alignment
Validation
git diff --check