Merge pull request #3179 from itowlson/schema-moar-docs

Fuller and more explicit docs in manifest schema

Author: itowlson

crates/manifest/src/schema/common.rs

@@ -5,43 +5,96 @@ use serde::{Deserialize, Serialize};
 
 use wasm_pkg_common::{package::PackageRef, registry::Registry};
 
-/// Variable definition
+use super::json_schema;
+
+/// The name of the application variable.
 #[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]
 #[serde(deny_unknown_fields)]
 pub struct Variable {
-    /// `required = true`
+    /// Whether a value must be supplied at runtime. If not specified, required defaults
+    /// to `false`, and `default` must be provided.
+    ///
+    /// Example: `required = true`
+    ///
+    /// Learn more: https://spinframework.dev/variables#adding-variables-to-your-applications
     #[serde(default, skip_serializing_if = "is_false")]
     pub required: bool,
-    /// `default = "default value"`
+    /// The value of the variable if no value is supplied at runtime. If specified,
+    /// the value must be a string. If not specified, `required`` must be `true`.
+    ///
+    /// Example: `default = "default value"`
+    ///
+    /// Learn more: https://spinframework.dev/variables#adding-variables-to-your-applications
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub default: Option<String>,
-    /// `secret = true`
+    /// If set, this variable should be treated as sensitive.
+    ///
+    /// Example: `secret = true`
+    ///
+    /// Learn more: https://spinframework.dev/variables#adding-variables-to-your-applications
     #[serde(default, skip_serializing_if = "is_false")]
     pub secret: bool,
 }
 
-/// Component source
+/// The file, package, or URL containing the component Wasm binary. This may be:
+///
+/// - The path to a Wasm file (relative to the manifest file)
+///
+/// Example: `source = "bin/cart.wasm"`
+///
+/// - The URL of a Wasm file downloadable over HTTP, accompanied by a digest to ensure integrity
+///
+/// Example: `source = { url = "https://example.com/example.wasm", digest = "sha256:6503...2375" }`
+///
+/// - The registry, package and version of a component from a registry
+///
+/// Example: `source = { registry = "ttl.sh", package = "user:registrytest", version="1.0.0" }`
+///
+/// Learn more: https://spinframework.dev/writing-apps#the-component-source
 #[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]
 #[serde(deny_unknown_fields, untagged)]
 pub enum ComponentSource {
-    /// `"local.wasm"`
+    /// `source = "bin/cart.wasm"`
+    #[schemars(description = "")] // schema docs are on the parent
     Local(String),
-    /// `{ ... }`
+    /// `source = { url = "https://example.com/example.wasm", digest = "sha256:6503...2375" }`
+    #[schemars(description = "")] // schema docs are on the parent
     Remote {
-        /// `url = "https://example.test/remote.wasm"`
+        /// The URL of the Wasm component binary.
+        ///
+        /// Example: `url = "https://example.test/remote.wasm"`
+        ///
+        /// Learn more: https://spinframework.dev/writing-apps#the-component-source
         url: String,
-        /// `digest = `"sha256:abc123..."`
+        /// The SHA256 digest of the Wasm component binary. This must be prefixed with `sha256:`.
+        ///
+        /// Example: `digest = `"sha256:abc123..."`
+        ///
+        /// Learn more: https://spinframework.dev/writing-apps#the-component-source
         digest: String,
     },
-    /// `{ ... }`
+    /// `source = { registry = "ttl.sh", package = "user:registrytest", version="1.0.0" }`
+    #[schemars(description = "")] // schema docs are on the parent
     Registry {
-        /// `registry = "example.com"`
+        /// The registry containing the Wasm component binary.
+        ///
+        /// Example: `registry = "example.com"`
+        ///
+        /// Learn more: https://spinframework.dev/writing-apps#the-component-source
         #[schemars(with = "Option<String>")]
         registry: Option<Registry>,
-        /// `package = "example:component"`
+        /// The package containing the Wasm component binary.
+        ///
+        /// Example: `package = "example:component"`
+        ///
+        /// Learn more: https://spinframework.dev/writing-apps#the-component-source
         #[schemars(with = "String")]
         package: PackageRef,
-        /// `version = "1.2.3"`
+        /// The version of the package containing the Wasm component binary.
+        ///
+        /// Example: `version = "1.2.3"`
+        ///
+        /// Learn more: https://spinframework.dev/writing-apps#the-component-source
         version: String,
     },
 }
@@ -66,17 +119,33 @@ impl Display for ComponentSource {
     }
 }
 
-/// WASI files mount
+/// The files the component is allowed to read. Each list entry is either:
+///
+/// - a glob pattern (e.g. "assets/**/*.jpg"); or
+///
+/// - a source-destination pair indicating where a host directory should be mapped in the guest (e.g. { source = "assets", destination = "/" })
+///
+/// Learn more: https://spinframework.dev/writing-apps#including-files-with-components
 #[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]
 #[serde(deny_unknown_fields, untagged)]
 pub enum WasiFilesMount {
     /// `"images/*.png"`
+    #[schemars(description = "")] // schema docs are on the parent
     Pattern(String),
     /// `{ ... }`
+    #[schemars(description = "")] // schema docs are on the parent
     Placement {
-        /// `source = "content/dir"`
+        /// The directory to be made available in the guest.
+        ///
+        /// Example: `source = "content/dir"`
+        ///
+        /// Learn more: https://spinframework.dev/writing-apps#including-files-with-components
         source: String,
+        /// The path where the `source` directory appears in the guest. Must be absolute.
+        ///
         /// `destination = "/"`
+        ///
+        /// Learn more: https://spinframework.dev/writing-apps#including-files-with-components
         destination: String,
     },
 }
@@ -85,13 +154,30 @@ pub enum WasiFilesMount {
 #[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]
 #[serde(deny_unknown_fields)]
 pub struct ComponentBuildConfig {
-    /// `command = "cargo build"`
+    /// The command or commands to build the application. If multiple commands
+    /// are specified, they are run sequentially from left to right.
+    ///
+    /// Example: `command = "cargo build"`, `command = ["npm install", "npm run build"]`
+    ///
+    /// Learn more: https://spinframework.dev/build#setting-up-for-spin-build
     pub command: Commands,
-    /// `workdir = "components/main"
+    /// The working directory for the build command. If omitted, the build working
+    /// directory is the directory containing `spin.toml`.
+    ///
+    /// Example: `workdir = "components/main"
+    ///
+    /// Learn more: https://spinframework.dev/build#overriding-the-working-directory
     #[serde(default, skip_serializing_if = "Option::is_none")]
     pub workdir: Option<String>,
-    /// watch = ["src/**/*.rs"]
+    /// Source files to use in `spin watch`. This is a set of paths or glob patterns (relative
+    /// to the build working directory). A change to any matching file causes
+    /// `spin watch` to rebuild the application before restarting the application.
+    ///
+    /// Example: `watch = ["src/**/*.rs"]`
+    ///
+    /// Learn more: https://spinframework.dev/running-apps#monitoring-applications-for-changes
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    #[schemars(with = "Vec<json_schema::WatchCommand>")]
     pub watch: Vec<String>,
 }
 
@@ -106,13 +192,20 @@ impl ComponentBuildConfig {
     }
 }
 
-/// Component build command or commands
+/// The command or commands to build the application. If multiple commands
+/// are specified, they are run sequentially from left to right.
+///
+/// Example: `command = "cargo build"`, `command = ["npm install", "npm run build"]`
+///
+/// Learn more: https://spinframework.dev/build#setting-up-for-spin-build
 #[derive(Clone, Debug, Serialize, Deserialize, JsonSchema)]
 #[serde(untagged)]
 pub enum Commands {
     /// `command = "cargo build"`
+    #[schemars(description = "")] // schema docs are on the parent
     Single(String),
     /// `command = ["cargo build", "wac encode compose-deps.wac -d my:pkg=app.wasm --registry fermyon.com"]`
+    #[schemars(description = "")] // schema docs are on the parent
     Multiple(Vec<String>),
 }
 

crates/manifest/src/schema/json_schema.rs

@@ -39,9 +39,25 @@ pub struct HttpTriggerSchema {
 #[derive(JsonSchema)]
 #[schemars(untagged)]
 pub enum HttpRouteSchema {
-    /// `route = "/user/:name/..."`
+    /// The HTTP route that the trigger accepts. The route must begin with a `/``.
+    /// The route may contain:
+    ///
+    /// - Any number of single-segment wildcards, using the syntax `:name`. It matches only a single segment of a path, and allows further matching on segments beyond it.
+    ///
+    /// - A trailing wildcard, using the syntax `/...`. This matches the given route and any route under it.
+    ///
+    /// In particular, the route `/...` matches _all_ paths.
+    ///
+    /// Example: `route = "/user/:name/..."`
+    ///
+    /// Learn more: https://spinframework.dev/v3/http-trigger#http-trigger-routes
     Route(String),
-    /// `route = { private = true }`
+    /// The trigger does not response to any external HTTP request, but only to requests
+    /// via local service chaining.
+    ///
+    /// Example: `route = { private = true }`
+    ///
+    /// Learn more: https://spinframework.dev/v3/http-trigger#private-endpoints
     Private(HttpPrivateEndpoint),
 }
 
@@ -73,6 +89,80 @@ pub struct RedisTriggerSchema {
     address: Option<String>,
 }
 
+/// The SQLite databases which the component is allowed to access. Databases are identified
+/// by label e.g. "default" or "analytics". Databases other than "default" must be mapped
+/// to a backing store in the runtime config. Use "spin up --sqlite" to run database setup scripts.
+///
+/// Example: `sqlite_databases = ["default", "my-database"]`
+///
+/// Learn more: https://spinframework.dev/sqlite-api-guide#preparing-an-sqlite-database
+#[allow(dead_code)]
+#[derive(JsonSchema)]
+#[serde(untagged)]
+pub enum SqliteDatabase {
+    Label(String),
+}
+
+/// The key-value stores which the component is allowed to access. Stores are identified
+/// by label e.g. "default" or "customer". Stores other than "default" must be mapped
+/// to a backing store in the runtime config.
+///
+/// Example: `key_value_stores = ["default", "my-store"]`
+///
+/// Learn more: https://spinframework.dev/kv-store-api-guide#custom-key-value-stores
+#[allow(dead_code)]
+#[derive(JsonSchema)]
+#[serde(untagged)]
+pub enum KeyValueStore {
+    Label(String),
+}
+
+/// The network destinations which the component is allowed to access.
+/// Each entry is in the form "(scheme)://(host)[:port]". Each element
+/// allows * as a wildcard e.g. "https://\*" (HTTPS on the default port
+/// to any destination) or "\*://localhost:\*" (any protocol to any port on
+/// localhost). The host part allows segment wildcards for subdomains
+/// e.g. "https://\*.example.com". Application variables are allowed using
+/// `{{ my_var }}`` syntax.
+///
+/// Example: `allowed_outbound_hosts = ["redis://myredishost.com:6379"]`
+///
+/// Learn more: https://spinframework.dev/http-outbound#granting-http-permissions-to-components
+#[allow(dead_code)]
+#[derive(JsonSchema)]
+#[serde(untagged)]
+pub enum AllowedOutboundHost {
+    Host(String),
+}
+
+/// The AI models which the component is allowed to access. For local execution, you must
+/// download all models; for hosted execution, you should check which models are available
+/// in your target environment.
+///
+/// Example: `ai_models = ["llama2-chat"]`
+///
+/// Learn more: https://spinframework.dev/serverless-ai-api-guide#using-serverless-ai-from-applications
+#[allow(dead_code)]
+#[derive(JsonSchema)]
+#[serde(untagged)]
+pub enum AIModel {
+    Label(String),
+}
+
+/// Source files to use in `spin watch`. This is a set of paths or glob patterns (relative
+/// to the build working directory). A change to any matching file causes
+/// `spin watch` to rebuild the application before restarting the application.
+///
+/// Example: `watch = ["src/**/*.rs"]`
+///
+/// Learn more: https://spinframework.dev/running-apps#monitoring-applications-for-changes
+#[allow(dead_code)]
+#[derive(JsonSchema)]
+#[serde(untagged)]
+pub enum WatchCommand {
+    Command(String),
+}
+
 pub fn toml_table(_gen: &mut schemars::gen::SchemaGenerator) -> schemars::schema::Schema {
     schemars::schema::Schema::Object(schemars::schema::SchemaObject {
         instance_type: Some(schemars::schema::SingleOrVec::Single(Box::new(