Merge pull request #332 from arlyon/feat/improve-api-docs

feat: improve api doc code to fix / add more coverage

Author: arlyon

openapi/src/url_finder.rs

@@ -7,7 +7,7 @@ const APP_USER_AGENT: &str = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWeb
 
 #[derive(Debug)]
 pub struct UrlFinder {
-    html: String,
+    flattened_api_sections: serde_json::Map<String, serde_json::Value>,
 }
 
 impl UrlFinder {
@@ -17,8 +17,16 @@ impl UrlFinder {
 
         if resp.status().is_success() {
             let text = resp.text()?;
-            if text.contains("title: 'Stripe API Reference'") {
-                Ok(Self { html: text })
+            if let Some(line) = text.lines().find(|l| l.contains("flattenedAPISections: {")) {
+                println!("{}", line);
+                Ok(Self {
+                    flattened_api_sections: serde_json::from_str(
+                        line.trim()
+                            .trim_start_matches("flattenedAPISections: ")
+                            .trim_end_matches(","),
+                    )
+                    .expect("should be valid json"),
+                })
             } else {
                 Err(anyhow!("stripe api returned unexpected document"))
             }
@@ -30,12 +38,19 @@ impl UrlFinder {
 
     pub fn url_for_object(&self, object: &str) -> Option<String> {
         let object_name = object.replace('.', "_").to_snake_case();
-        let doc_url = format!("/{}s/object", object_name);
-        if self.html.contains(&doc_url) {
-            Some(format!("https://stripe.com/docs/api{}", doc_url))
-        } else {
-            log::warn!("{} not in html", doc_url);
-            None
+        let object_names = [format!("{}_object", object_name), object_name];
+        for name in object_names {
+            if let Some(path) = self
+                .flattened_api_sections
+                .get(&name)
+                .and_then(|o| o.as_object().expect("this should be an object").get("path"))
+                .and_then(|s| s.as_str())
+            {
+                return Some(format!("https://stripe.com/docs/api{}", path));
+            }
         }
+
+        log::warn!("{} not in html", object);
+        None
     }
 }

src/resources/generated/balance.rs

@@ -8,6 +8,8 @@ use crate::params::Object;
 use crate::resources::Currency;
 
 /// The resource representing a Stripe "Balance".
+///
+/// For more details see <https://stripe.com/docs/api/balance/balance_object>
 #[derive(Clone, Debug, Default, Deserialize, Serialize)]
 pub struct Balance {
     /// Funds that are available to be transferred or paid out, whether automatically by Stripe or explicitly via the [Transfers API](https://stripe.com/docs/api#transfers) or [Payouts API](https://stripe.com/docs/api#payouts).

src/resources/generated/capability.rs

@@ -8,6 +8,8 @@ use crate::resources::{Account};
 use serde::{Deserialize, Serialize};
 
 /// The resource representing a Stripe "AccountCapability".
+///
+/// For more details see <https://stripe.com/docs/api/capabilities/object>
 #[derive(Clone, Debug, Default, Deserialize, Serialize)]
 pub struct Capability {
     /// The identifier for the capability.

src/resources/generated/cash_balance.rs

@@ -7,6 +7,8 @@ use serde::{Deserialize, Serialize};
 use crate::params::Object;
 
 /// The resource representing a Stripe "cash_balance".
+///
+/// For more details see <https://stripe.com/docs/api/cash_balance/object>
 #[derive(Clone, Debug, Default, Deserialize, Serialize)]
 pub struct CashBalance {
     /// A hash of all cash balances available to this customer.

src/resources/generated/checkout_session.rs

@@ -15,6 +15,8 @@ use crate::resources::{
 };
 
 /// The resource representing a Stripe "Session".
+///
+/// For more details see <https://stripe.com/docs/api/checkout/sessions/object>
 #[derive(Clone, Debug, Default, Deserialize, Serialize)]
 pub struct CheckoutSession {
     /// Unique identifier for the object.

src/resources/generated/credit_note_line_item.rs

@@ -8,6 +8,8 @@ use crate::resources::{Discount, TaxRate};
 use serde::{Deserialize, Serialize};
 
 /// The resource representing a Stripe "CreditNoteLineItem".
+///
+/// For more details see <https://stripe.com/docs/api/credit_notes/line_item>
 #[derive(Clone, Debug, Default, Deserialize, Serialize)]
 pub struct CreditNoteLineItem {
     /// Unique identifier for the object.

src/resources/generated/customer_cash_balance_transaction.rs

@@ -8,6 +8,8 @@ use crate::resources::{Currency, Customer, PaymentIntent, Refund};
 use serde::{Deserialize, Serialize};
 
 /// The resource representing a Stripe "CustomerCashBalanceTransaction".
+///
+/// For more details see <https://stripe.com/docs/api/cash_balance_transactions/object>
 #[derive(Clone, Debug, Default, Deserialize, Serialize)]
 pub struct CustomerCashBalanceTransaction {
     /// Unique identifier for the object.

src/resources/generated/financial_connections_account.rs

@@ -8,6 +8,8 @@ use crate::resources::{BankConnectionsResourceAccountholder, FinancialConnection
 use serde::{Deserialize, Serialize};
 
 /// The resource representing a Stripe "BankConnectionsResourceLinkedAccount".
+///
+/// For more details see <https://stripe.com/docs/api/financial_connections/accounts/object>
 #[derive(Clone, Debug, Default, Deserialize, Serialize)]
 pub struct FinancialConnectionsAccount {
     /// Unique identifier for the object.

src/resources/generated/financial_connections_session.rs

@@ -9,6 +9,8 @@ use crate::resources::{BankConnectionsResourceAccountholder, FinancialConnection
 use serde::{Deserialize, Serialize};
 
 /// The resource representing a Stripe "BankConnectionsResourceLinkAccountSession".
+///
+/// For more details see <https://stripe.com/docs/api/financial_connections/sessions/object>
 #[derive(Clone, Debug, Default, Deserialize, Serialize)]
 pub struct FinancialConnectionsSession {
     /// Unique identifier for the object.

src/resources/generated/identity_verification_report.rs

@@ -8,6 +8,8 @@ use crate::resources::{Address};
 use serde::{Deserialize, Serialize};
 
 /// The resource representing a Stripe "GelatoVerificationReport".
+///
+/// For more details see <https://stripe.com/docs/api/identity/verification_reports/object>
 #[derive(Clone, Debug, Default, Deserialize, Serialize)]
 pub struct IdentityVerificationReport {
     /// Unique identifier for the object.