Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
25 changes: 24 additions & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,28 @@
## Generate code
# Contributing

## Code generation

Regenerate the Rust SDK from `openapi.json` with:

```sh
cargo xtask generate
```

Generate the deterministic JSON catalog of developer-portal code samples with:

```sh
cargo xtask generate-code-samples
```

The default output is the ignored `code-samples.json` at the repository root.
Use `--output <path>` to write it elsewhere. Every sample is a complete Rust
program, and named OpenAPI request examples are emitted as separate catalog
entries. To regenerate twice and compile every program against the local SDK,
run:

```sh
cargo xtask validate-code-samples
```

Published releases synchronize this catalog to
`sumup/sumup-developer` as `src/codesamples/rust.json`.
44 changes: 18 additions & 26 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,6 +59,23 @@ let client = Client::default()
.with_authorization(Authorization::api_key("your_api_key"));
```

## Handling errors

API errors retain their HTTP status, headers, and original response bytes. Read typed
Problem details directly when available:

```rust
if let Err(error) = client.checkouts().get("your-checkout-id").await {
if let Some(problem) = error.problem() {
println!("{}: {}", problem.r#type, problem.detail.as_deref().unwrap_or("Request failed"));
}
println!("{:?}", error.status());
}
```

Use `status()` and `headers()` to inspect the HTTP response, `raw_body()` for its
original bytes, and `body()` for other typed error details.

## HTTP Configuration

The SDK uses `reqwest` as its HTTP transport. You can provide a configured
Expand Down Expand Up @@ -110,31 +127,6 @@ You can find all examples under [examples/](/examples/). To run an example, use:
cargo run --example checkout_card_reader
```

## Code generation

Regenerate the Rust SDK from `openapi.json` with:

```sh
cargo xtask generate
```

Generate the deterministic JSON catalog of developer-portal code samples with:

```sh
cargo xtask generate-code-samples
```

The default output is the ignored `code-samples.json` at the repository root.
Use `--output <path>` to write it elsewhere. Every sample is a complete Rust
program, and named OpenAPI request examples are emitted as separate catalog
entries. To regenerate twice and compile every program against the local SDK,
run:

```sh
cargo xtask validate-code-samples
```

Published releases synchronize this catalog to
`sumup/sumup-developer` as `src/codesamples/rust.json`.
For development instructions, see [Contributing](CONTRIBUTING.md).

[docs-badge]: https://img.shields.io/badge/SumUp-documentation-white.svg?logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgY29sb3I9IndoaXRlIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciPgogICAgPHBhdGggZD0iTTIyLjI5IDBIMS43Qy43NyAwIDAgLjc3IDAgMS43MVYyMi4zYzAgLjkzLjc3IDEuNyAxLjcxIDEuN0gyMi4zYy45NCAwIDEuNzEtLjc3IDEuNzEtMS43MVYxLjdDMjQgLjc3IDIzLjIzIDAgMjIuMjkgMFptLTcuMjIgMTguMDdhNS42MiA1LjYyIDAgMCAxLTcuNjguMjQuMzYuMzYgMCAwIDEtLjAxLS40OWw3LjQ0LTcuNDRhLjM1LjM1IDAgMCAxIC40OSAwIDUuNiA1LjYgMCAwIDEtLjI0IDcuNjlabTEuNTUtMTEuOS03LjQ0IDcuNDVhLjM1LjM1IDAgMCAxLS41IDAgNS42MSA1LjYxIDAgMCAxIDcuOS03Ljk2bC4wMy4wM2MuMTMuMTMuMTQuMzUuMDEuNDlaIiBmaWxsPSJjdXJyZW50Q29sb3IiLz4KPC9zdmc+
50 changes: 32 additions & 18 deletions codegen/src/operation.rs
Original file line number Diff line number Diff line change
Expand Up @@ -709,6 +709,7 @@ fn generate_error_handling(
let enum_ident = Ident::new(&enum_name, Span::call_site());

let mut variant_defs = Vec::new();
let mut problem_arms = Vec::new();
let mut seen_variants: Vec<String> = Vec::new();
let mut match_arms = Vec::new();

Expand All @@ -722,9 +723,16 @@ fn generate_error_handling(
match &body_kind {
BodyKind::Schema(ident) => {
variant_defs.push(quote! { #variant_ident(#ident), });
if ident == "Problem" {
problem_arms
.push(quote! { Self::#variant_ident(problem) => Some(problem), });
}
}
BodyKind::Unknown => {
variant_defs.push(quote! { #variant_ident(crate::error::UnknownApiBody), });
problem_arms.push(quote! {
Self::#variant_ident(body) => crate::error::ProblemDetails::problem(body),
});
}
BodyKind::Empty => {
variant_defs.push(quote! { #variant_ident, });
Expand All @@ -737,35 +745,49 @@ fn generate_error_handling(
BodyKind::Schema(ident) => {
match_arms.push(quote! {
#status_const => {
let body: #ident = response.json().await?;
Err(crate::error::SdkError::api(#enum_ident::#variant_ident(body)))
Err(crate::error::SdkError::from_response(response, |raw| {
serde_json::from_slice::<#ident>(raw).map(#enum_ident::#variant_ident)
}).await)
}
});
}
BodyKind::Unknown => {
match_arms.push(quote! {
#status_const => {
let body_bytes = response.bytes().await?;
let body = crate::error::UnknownApiBody::from_bytes(body_bytes.as_ref());
Err(crate::error::SdkError::api(#enum_ident::#variant_ident(body)))
Err(crate::error::SdkError::from_response(response, |raw| {
Ok(#enum_ident::#variant_ident(crate::error::UnknownApiBody::from_bytes(raw)))
}).await)
}
});
}
BodyKind::Empty => {
match_arms.push(quote! {
#status_const => {
Err(crate::error::SdkError::api(#enum_ident::#variant_ident))
Err(crate::error::SdkError::from_response(response, |_| Ok(#enum_ident::#variant_ident)).await)
}
});
}
}
}

let problem_body = if problem_arms.is_empty() {
quote! { None }
} else if problem_arms.len() == variant_defs.len() {
quote! { match self { #(#problem_arms)* } }
} else {
quote! { match self { #(#problem_arms)* _ => None } }
};

let body_definition = Some(quote! {
#[derive(Debug, PartialEq)]
pub enum #enum_ident {
#(#variant_defs)*
}
impl crate::error::ProblemDetails for #enum_ident {
fn problem(&self) -> Option<&crate::resources::common::Problem> {
#problem_body
}
}
});

Ok(ErrorGeneration {
Expand Down Expand Up @@ -866,9 +888,7 @@ fn generate_no_success_response_handling(
match status {
#(#error_arms)*
_ => {
let body_bytes = response.bytes().await?;
let body = crate::error::UnknownApiBody::from_bytes(body_bytes.as_ref());
Err(crate::error::SdkError::unexpected(status, body))
Err(crate::error::SdkError::unexpected_response(response).await)
}
}
}
Expand Down Expand Up @@ -907,9 +927,7 @@ fn generate_single_response_handling(
}
#(#error_arms)*
_ => {
let body_bytes = response.bytes().await?;
let body = crate::error::UnknownApiBody::from_bytes(body_bytes.as_ref());
Err(crate::error::SdkError::unexpected(status, body))
Err(crate::error::SdkError::unexpected_response(response).await)
}
}
})
Expand All @@ -920,9 +938,7 @@ fn generate_single_response_handling(
#status_const => Ok(()),
#(#error_arms)*
_ => {
let body_bytes = response.bytes().await?;
let body = crate::error::UnknownApiBody::from_bytes(body_bytes.as_ref());
Err(crate::error::SdkError::unexpected(status, body))
Err(crate::error::SdkError::unexpected_response(response).await)
}
}
})
Expand Down Expand Up @@ -1023,9 +1039,7 @@ fn generate_multi_response_handling(
#(#match_arms)*
#(#error_arms)*
_ => {
let body = response.text().await?;
let body = crate::error::UnknownApiBody::from_text(body);
Err(crate::error::SdkError::unexpected(status, body))
Err(crate::error::SdkError::unexpected_response(response).await)
}
}
})
Expand Down
Loading
Loading