Function generate_document

ra-rpc/src/openapi.rs:228–309

Builds an OpenAPI specification for the provided descriptor sources.

(
    sources: &[DescriptorSource<'_>],
    info: &DocumentInfo<'_>,
)

/// Builds an OpenAPI specification for the provided descriptor sources.
pub fn generate_document(
    sources: &[DescriptorSource<'_>],
    info: &DocumentInfo<'_>,
) -> Result<String> {
    if sources.is_empty() {
        bail!("at least one descriptor source is required");
    }

    let mut registry = DescriptorRegistry::default();
    for (source_id, source) in sources.iter().enumerate() {
        let descriptor_set = FileDescriptorSet::decode(source.descriptor)
            .context("failed to decode descriptor set")?;
        registry.ingest(descriptor_set, source_id);
    }

    let mut schema_builder = SchemaBuilder::new(&registry);
    let mut paths = BTreeMap::<String, Value>::new();

    for (source_id, source) in sources.iter().enumerate() {
        for svc_cfg in &source.services {
            let service = registry
                .resolve_service(source_id, svc_cfg.name.as_ref())
                .with_context(|| format!("service {} not found in descriptor", svc_cfg.name))?;

            for method in &service.methods {
                if method.client_streaming || method.server_streaming {
                    bail!(
                        "streaming method {}.{} is not supported by the HTTP bridge",
                        service.full_name,
                        method.name
                    );
                }

                let base = normalize_mount_path(svc_cfg.mount_path.as_ref());
                let method_segment = format!("{}{}", svc_cfg.method_prefix, method.name);
                let path = join_path(&base, &method_segment);
                let post_operation =
                    build_operation(service, method, svc_cfg, &mut schema_builder)?;

                let mut op_map = Map::new();
                op_map.insert("post".to_string(), post_operation);
                paths.insert(path, Value::Object(op_map));
            }
        }
    }

    if paths.is_empty() {
        bail!("no RPC methods were registered for OpenAPI export");
    }

    let mut schemas = schema_builder.finish();
    schemas.insert("RpcError".to_string(), rpc_error_schema());

    let mut doc = Map::new();
    doc.insert("openapi".into(), Value::String("3.1.0".into()));

    let mut info_obj = Map::new();
    info_obj.insert("title".into(), Value::String(info.title.to_string()));