Skip to content

Add x-codeSamples to generated OpenAPI #4371

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+2,422 −345
Open

Add x-codeSamples to generated OpenAPI #4371

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 40 additions & 3 deletions compiler-rs/clients_schema_to_openapi/src/paths.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -168,7 +168,7 @@ pub fn add_endpoint(
let media = MediaType {
schema: Some(schema),
example: None,
examples: request_examples,
examples: request_examples.clone(),
encoding: Default::default(),
extensions: Default::default(),
};
Expand Down Expand Up @@ -198,7 +198,7 @@ pub fn add_endpoint(
// If this endpoint response has examples in schema.json, convert them to the
// OpenAPI format and add them to the endpoint response in the OpenAPI document.
let response_examples = if let Some(examples) = &response_def.examples {
get_openapi_examples(examples)
get_openapi_examples(examples)
} else {
IndexMap::new()
};
Expand Down Expand Up @@ -251,6 +251,43 @@ pub fn add_endpoint(

let sum_desc = split_summary_desc(&endpoint.description);

// add the x-state extension for availability
let mut extensions = crate::availability_as_extensions(&endpoint.availability);

// add the x-codeSamples extension
if !request_examples.is_empty() {
let mut code_samples = vec![];
if let Some((_, first_example)) = request_examples.clone().first() {
if let Some(example) = first_example.as_item() {
if let Some(description) = example.description.clone() {
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we use summary when description is not set?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This feature does not need summaries or descriptions, all I'm doing here is parsing the description text with the hope that somewhere within it I can find the method and URL of the request. The only reason I'm using description is because that is how these examples are parsed.

The proper thing to do would be to expand these examples to include this information in a easier format, at which point there wouldn't be a need to use descriptions or summaries for anything.

let mut request: Option<String> = Option::None;
for r in description.split('`') {
if r.starts_with("GET ")
|| r.starts_with("POST ")
|| r.starts_with("PUT ")
|| r.starts_with("DELETE ")
|| r.starts_with("HEAD ")
{
request = Some(String::from(r));
break;
}
Comment on lines +265 to +273
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we have examples that don't start with a method? QUERY will be a thing soon!

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is really a hack. I hope we don't have to do this. The problem is that the examples that were added to this repository are not clean Dev Console examples, so I'm forced to reconstruct the DevConsole syntax.

}
if let Some(first_line) = request {
if let Some(code) = example.value.clone() {
code_samples.push(serde_json::json!({
"lang": "Console",
"source": first_line + "\n" + code.as_str().unwrap_or(""),
}));
}
}
}
}
}
if code_samples.len() > 0 {
extensions.insert("x-codeSamples".to_string(), serde_json::json!(code_samples));
}
}

// Create the operation, it will be repeated if we have several methods
let operation = openapiv3::Operation {
tags: if let Some(doc_tag) = &endpoint.doc_tag {
Expand All @@ -274,7 +311,7 @@ pub fn add_endpoint(
deprecated: endpoint.deprecation.is_some(),
security: None,
servers: vec![],
extensions: crate::availability_as_extensions(&endpoint.availability),
extensions,
};


Expand Down
Binary file modified compiler-rs/compiler-wasm-lib/pkg/compiler_wasm_lib_bg.wasm
View file
Open in desktop
Binary file not shown.
Loading
Loading