Merge pull request #695 from dkackman/swagger

Swagger

Author: Rigidity

.gitignore

@@ -25,5 +25,6 @@ dist-ssr
 
 # Rust
 target
-/.env
+.env
 /test.sqlite*
+

Cargo.lock

@@ -84,6 +84,9 @@ specta = "2.0.0-rc.20"
 specta-typescript = "0.0.7"
 tauri-specta = "2.0.0-rc.20"
 
+# OpenAPI
+utoipa = "5.2.0"
+
 # Chia
 chia = "0.26.0"
 chia_streamable_macro = "0.26.0"
@@ -123,6 +126,7 @@ expect-test = "1.5.1"
 convert_case = "0.8.0"
 quote = "1.0.38"
 proc-macro2 = "1.0.93"
+syn = "2.0"
 
 # Tracing
 tracing = "0.1.40"

Cargo.toml

@@ -116,3 +116,5 @@ The following things have to be done before a new release is published:
 4. Run `pnpm extract` to extract new translations
 5. Create a new tagged release
 6. Upload to TestFlight and the Google Play Store
+7. Generate the OpenAPI specification `cargo run --bin sage rpc generate_openapi -o dist/openapi.json`
+8. Upload to docusaurus

README.md

@@ -16,9 +16,12 @@ workspace = true
 
 [features]
 tauri = ["dep:tauri-specta", "dep:specta"]
+openapi = ["dep:utoipa", "dep:sage-api-macro"]
 
 [dependencies]
 sage-config = { workspace = true }
+sage-api-macro = { workspace = true, optional = true }
 serde = { workspace = true, features = ["derive"] }
 tauri-specta = { workspace = true, features = ["derive"], optional = true }
 specta = { workspace = true, features = ["derive", "bigdecimal"], optional = true }
+utoipa = { workspace = true, optional = true }

crates/sage-api/Cargo.toml

@@ -23,3 +23,4 @@ convert_case = { workspace = true }
 serde_json = { workspace = true }
 indexmap = { workspace = true, features = ["serde"] }
 proc-macro2 = { workspace = true }
+syn = { workspace = true, features = ["full"] }

crates/sage-api/macro/Cargo.toml

@@ -1,8 +1,10 @@
+mod openapi;
+
 use convert_case::{Case, Casing};
 use indexmap::IndexMap;
 use proc_macro::{Delimiter, Group, TokenStream, TokenTree};
-use proc_macro2::Ident;
 use quote::quote;
+use syn::parse_macro_input;
 
 #[proc_macro]
 pub fn impl_endpoints(input: TokenStream) -> TokenStream {
@@ -14,6 +16,58 @@ pub fn impl_endpoints_tauri(input: TokenStream) -> TokenStream {
     generate(&input, true)
 }
 
+/// Attribute macro for `OpenAPI` metadata
+///
+/// Usage:
+/// ```
+/// #[openapi(
+///     tag = "Authentication & Keys",
+///     description = "Authenticate and log into a wallet..."
+/// )]
+/// pub struct Login { ... }
+/// ```
+#[proc_macro_attribute]
+pub fn openapi(args: TokenStream, input: TokenStream) -> TokenStream {
+    let args = parse_macro_input!(args as openapi::OpenApiArgs);
+    let input = parse_macro_input!(input as syn::DeriveInput);
+
+    openapi::impl_openapi_metadata(&args, &input).into()
+}
+
+/// Generates schema registrations from endpoints.json
+///
+/// Automatically reads endpoints.json and generates `.schema_from::<Type>()`
+/// calls for all endpoint request/response types.
+#[proc_macro]
+pub fn register_openapi_types(input: TokenStream) -> TokenStream {
+    openapi::impl_openapi_registration(input)
+}
+
+/// Generates endpoint metadata match arms from endpoints.json
+///
+/// Automatically generates match arms that retrieve tag and description
+/// from `OpenApiMetadata` trait implementations.
+#[proc_macro]
+pub fn endpoint_metadata(input: TokenStream) -> TokenStream {
+    openapi::impl_endpoint_metadata(input)
+}
+
+/// Generates request schema match arms from endpoints.json
+///
+/// Automatically generates match arms mapping endpoints to their request schemas.
+#[proc_macro]
+pub fn request_schemas(input: TokenStream) -> TokenStream {
+    openapi::impl_request_schemas(input)
+}
+
+/// Generates response schema match arms from endpoints.json
+///
+/// Automatically generates match arms mapping endpoints to their response schemas.
+#[proc_macro]
+pub fn response_schemas(input: TokenStream) -> TokenStream {
+    openapi::impl_response_schemas(input)
+}
+
 fn generate(input: &TokenStream, tauri: bool) -> TokenStream {
     let mut endpoints: IndexMap<String, bool> =
         serde_json::from_str(include_str!("../../endpoints.json")).expect("Invalid endpoint file");
@@ -62,13 +116,13 @@ fn convert(
                     output.extend(quote!(.await));
                 }
             } else if ident.is_case(Case::Snake) {
-                let ident = Ident::new(
+                let ident = proc_macro2::Ident::new(
                     &ident.replace("endpoint", &endpoint.to_case(Case::Snake)),
                     old.span().into(),
                 );
                 output.extend(quote!(#ident));
             } else if ident.is_case(Case::Pascal) {
-                let ident = Ident::new(
+                let ident = proc_macro2::Ident::new(
                     &ident.replace("Endpoint", &endpoint.to_case(Case::Pascal)),
                     old.span().into(),
                 );