| @@ -213,8 +213,318 @@ | ||
| 213 | 213 | 'search' => [ 'type' => 'object' ] |
| 214 | 214 | ] |
| 215 | 215 | ], |
| 216 | 216 | 'annotations' => self::annotations( true, false, true, 1.0 ) |
| 217 | + ], | |
| 218 | + [ | |
| 219 | + 'id' => 'betterdocs-pro/list-api-references', | |
| 220 | + 'label' => __( 'List API references', 'betterdocs' ), | |
| 221 | + 'description' => __( 'List the API references on this site, each with its title, slug, status, source and whether its spec has been materialized into docs.', 'betterdocs' ), | |
| 222 | + 'feature' => __( 'API documentation', 'betterdocs' ), | |
| 223 | + 'capability' => 'manage_options', | |
| 224 | + 'kb_feature' => false, | |
| 225 | + 'input_schema' => [ | |
| 226 | + 'type' => 'object', | |
| 227 | + 'properties' => [], | |
| 228 | + 'default' => [] | |
| 229 | + ], | |
| 230 | + 'output_schema' => [ | |
| 231 | + 'type' => 'object', | |
| 232 | + 'properties' => [ | |
| 233 | + 'references' => [ 'type' => 'array' ], | |
| 234 | + 'total' => [ 'type' => 'integer' ], | |
| 235 | + 'max_references' => [ 'type' => [ 'integer', 'null' ] ] | |
| 236 | + ] | |
| 237 | + ], | |
| 238 | + 'annotations' => self::annotations( true, false, true, 1.0 ) | |
| 239 | + ], | |
| 240 | + [ | |
| 241 | + 'id' => 'betterdocs-pro/get-api-reference', | |
| 242 | + 'label' => __( 'Get API reference', 'betterdocs' ), | |
| 243 | + 'description' => __( 'Read one API reference by id: its settings and, when a spec has been ingested, a summary of the operations it documents.', 'betterdocs' ), | |
| 244 | + 'feature' => __( 'API documentation', 'betterdocs' ), | |
| 245 | + 'capability' => 'manage_options', | |
| 246 | + 'kb_feature' => false, | |
| 247 | + 'input_schema' => [ | |
| 248 | + 'type' => 'object', | |
| 249 | + 'properties' => [ | |
| 250 | + 'id' => [ | |
| 251 | + 'type' => 'integer', | |
| 252 | + 'description' => __( 'API reference id.', 'betterdocs' ) | |
| 253 | + ], | |
| 254 | + 'include_operations' => [ | |
| 255 | + 'type' => 'boolean', | |
| 256 | + 'description' => __( 'Include a summarized list of the spec operations (method, path, summary).', 'betterdocs' ) | |
| 257 | + ], | |
| 258 | + 'max_operations' => [ | |
| 259 | + 'type' => 'integer', | |
| 260 | + 'description' => __( 'Cap the number of operations returned when include_operations is true.', 'betterdocs' ) | |
| 261 | + ] | |
| 262 | + ], | |
| 263 | + 'required' => [ 'id' ] | |
| 264 | + ], | |
| 265 | + 'output_schema' => self::api_reference_schema(), | |
| 266 | + 'annotations' => self::annotations( true, false, true, 1.0 ) | |
| 267 | + ], | |
| 268 | + [ | |
| 269 | + 'id' => 'betterdocs-pro/create-api-reference', | |
| 270 | + 'label' => __( 'Create API reference', 'betterdocs' ), | |
| 271 | + 'description' => __( 'Create an API reference. Title, slug and status are optional; the title is filled from the spec\'s info.title when a spec is later ingested and none was set.', 'betterdocs' ), | |
| 272 | + 'feature' => __( 'API documentation', 'betterdocs' ), | |
| 273 | + 'capability' => 'manage_options', | |
| 274 | + 'kb_feature' => false, | |
| 275 | + 'input_schema' => [ | |
| 276 | + 'type' => 'object', | |
| 277 | + 'properties' => [ | |
| 278 | + 'title' => [ | |
| 279 | + 'type' => 'string', | |
| 280 | + 'description' => __( 'Reference title. Optional — filled from the spec when omitted.', 'betterdocs' ) | |
| 281 | + ], | |
| 282 | + 'slug' => [ | |
| 283 | + 'type' => 'string', | |
| 284 | + 'description' => __( 'URL slug. Derived from the title when omitted.', 'betterdocs' ) | |
| 285 | + ], | |
| 286 | + 'status' => [ | |
| 287 | + 'type' => 'string', | |
| 288 | + 'enum' => [ 'draft', 'publish' ], | |
| 289 | + 'description' => __( 'Publish state. Defaults to draft.', 'betterdocs' ) | |
| 290 | + ] | |
| 291 | + ] | |
| 292 | + ], | |
| 293 | + 'output_schema' => self::api_reference_schema(), | |
| 294 | + 'annotations' => self::annotations( false, false, false, 2.0 ) | |
| 295 | + ], | |
| 296 | + [ | |
| 297 | + 'id' => 'betterdocs-pro/update-api-reference', | |
| 298 | + 'label' => __( 'Update API reference', 'betterdocs' ), | |
| 299 | + 'description' => __( 'Update an API reference: rename it, change its slug or status, or adjust display settings such as the Try-it panel and code-sample theme.', 'betterdocs' ), | |
| 300 | + 'feature' => __( 'API documentation', 'betterdocs' ), | |
| 301 | + 'capability' => 'manage_options', | |
| 302 | + 'kb_feature' => false, | |
| 303 | + 'input_schema' => [ | |
| 304 | + 'type' => 'object', | |
| 305 | + 'properties' => [ | |
| 306 | + 'id' => [ | |
| 307 | + 'type' => 'integer', | |
| 308 | + 'description' => __( 'API reference id.', 'betterdocs' ) | |
| 309 | + ], | |
| 310 | + 'title' => [ | |
| 311 | + 'type' => 'string', | |
| 312 | + 'description' => __( 'New title.', 'betterdocs' ) | |
| 313 | + ], | |
| 314 | + 'slug' => [ | |
| 315 | + 'type' => 'string', | |
| 316 | + 'description' => __( 'New URL slug.', 'betterdocs' ) | |
| 317 | + ], | |
| 318 | + 'status' => [ | |
| 319 | + 'type' => 'string', | |
| 320 | + 'enum' => [ 'draft', 'publish' ], | |
| 321 | + 'description' => __( 'New publish state.', 'betterdocs' ) | |
| 322 | + ], | |
| 323 | + 'tryit_enabled' => [ | |
| 324 | + 'type' => 'boolean', | |
| 325 | + 'description' => __( 'Show the interactive Try-it panel.', 'betterdocs' ) | |
| 326 | + ], | |
| 327 | + 'tryit_label' => [ | |
| 328 | + 'type' => 'string', | |
| 329 | + 'description' => __( 'Label for the Try-it button.', 'betterdocs' ) | |
| 330 | + ], | |
| 331 | + 'code_theme' => [ | |
| 332 | + 'type' => 'string', | |
| 333 | + 'enum' => [ 'light', 'dark' ], | |
| 334 | + 'description' => __( 'Code-sample theme.', 'betterdocs' ) | |
| 335 | + ] | |
| 336 | + ], | |
| 337 | + 'required' => [ 'id' ] | |
| 338 | + ], | |
| 339 | + 'output_schema' => self::api_reference_schema(), | |
| 340 | + 'annotations' => self::annotations( false, false, true, 2.0 ) | |
| 341 | + ], | |
| 342 | + [ | |
| 343 | + 'id' => 'betterdocs-pro/delete-api-reference', | |
| 344 | + 'label' => __( 'Delete API reference', 'betterdocs' ), | |
| 345 | + 'description' => __( 'Delete an API reference and its stored spec. Docs already materialized from it are left in place, never deleted.', 'betterdocs' ), | |
| 346 | + 'feature' => __( 'API documentation', 'betterdocs' ), | |
| 347 | + 'capability' => 'manage_options', | |
| 348 | + 'kb_feature' => false, | |
| 349 | + 'input_schema' => [ | |
| 350 | + 'type' => 'object', | |
| 351 | + 'properties' => [ | |
| 352 | + 'id' => [ | |
| 353 | + 'type' => 'integer', | |
| 354 | + 'description' => __( 'API reference id.', 'betterdocs' ) | |
| 355 | + ] | |
| 356 | + ], | |
| 357 | + 'required' => [ 'id' ] | |
| 358 | + ], | |
| 359 | + 'output_schema' => [ | |
| 360 | + 'type' => 'object', | |
| 361 | + 'properties' => [ | |
| 362 | + 'id' => [ 'type' => 'integer' ], | |
| 363 | + 'title' => [ 'type' => 'string' ], | |
| 364 | + 'deleted' => [ 'type' => 'boolean' ] | |
| 365 | + ] | |
| 366 | + ], | |
| 367 | + 'annotations' => self::annotations( false, true, false, 2.0 ) | |
| 368 | + ], | |
| 369 | + [ | |
| 370 | + 'id' => 'betterdocs-pro/ingest-api-spec', | |
| 371 | + 'label' => __( 'Ingest API spec', 'betterdocs' ), | |
| 372 | + 'description' => __( 'Ingest an OpenAPI or Postman spec into an API reference. Pass the raw spec text, or a source_url to fetch it from; this replaces any previously ingested spec.', 'betterdocs' ), | |
| 373 | + 'feature' => __( 'API documentation', 'betterdocs' ), | |
| 374 | + 'capability' => 'manage_options', | |
| 375 | + 'kb_feature' => false, | |
| 376 | + 'input_schema' => [ | |
| 377 | + 'type' => 'object', | |
| 378 | + 'properties' => [ | |
| 379 | + 'id' => [ | |
| 380 | + 'type' => 'integer', | |
| 381 | + 'description' => __( 'API reference id to ingest into.', 'betterdocs' ) | |
| 382 | + ], | |
| 383 | + 'spec' => [ | |
| 384 | + 'type' => 'string', | |
| 385 | + 'description' => __( 'Raw spec document (JSON or YAML). Provide this or source_url.', 'betterdocs' ) | |
| 386 | + ], | |
| 387 | + 'source_url' => [ | |
| 388 | + 'type' => 'string', | |
| 389 | + 'description' => __( 'URL to fetch the spec from. Provide this or spec.', 'betterdocs' ) | |
| 390 | + ], | |
| 391 | + 'format' => [ | |
| 392 | + 'type' => 'string', | |
| 393 | + 'enum' => [ 'json', 'yaml' ], | |
| 394 | + 'description' => __( 'Serialization of the spec text. Sniffed when omitted.', 'betterdocs' ) | |
| 395 | + ] | |
| 396 | + ], | |
| 397 | + 'required' => [ 'id' ] | |
| 398 | + ], | |
| 399 | + 'output_schema' => [ | |
| 400 | + 'type' => 'object', | |
| 401 | + 'properties' => [ | |
| 402 | + 'id' => [ 'type' => 'integer' ], | |
| 403 | + 'result' => [ 'type' => 'string' ], | |
| 404 | + 'source_kind' => [ 'type' => 'string' ], | |
| 405 | + 'summary' => [ 'type' => [ 'object', 'null' ] ] | |
| 406 | + ] | |
| 407 | + ], | |
| 408 | + 'annotations' => self::annotations( false, false, false, 2.0 ) | |
| 409 | + ], | |
| 410 | + [ | |
| 411 | + 'id' => 'betterdocs-pro/materialize-api-reference', | |
| 412 | + 'label' => __( 'Materialize API reference', 'betterdocs' ), | |
| 413 | + 'description' => __( 'Turn an ingested API spec into BetterDocs docs, one per operation. Starts a background run and returns its state; call again with action "status" to check progress.', 'betterdocs' ), | |
| 414 | + 'feature' => __( 'API documentation', 'betterdocs' ), | |
| 415 | + 'capability' => 'manage_options', | |
| 416 | + 'kb_feature' => false, | |
| 417 | + 'input_schema' => [ | |
| 418 | + 'type' => 'object', | |
| 419 | + 'properties' => [ | |
| 420 | + 'id' => [ | |
| 421 | + 'type' => 'integer', | |
| 422 | + 'description' => __( 'API reference id.', 'betterdocs' ) | |
| 423 | + ], | |
| 424 | + 'action' => [ | |
| 425 | + 'type' => 'string', | |
| 426 | + 'enum' => [ 'run', 'status' ], | |
| 427 | + 'description' => __( 'run starts materialization; status reports an in-flight or finished run. Defaults to run.', 'betterdocs' ) | |
| 428 | + ] | |
| 429 | + ], | |
| 430 | + 'required' => [ 'id' ] | |
| 431 | + ], | |
| 432 | + 'output_schema' => [ | |
| 433 | + 'type' => 'object', | |
| 434 | + 'properties' => [ | |
| 435 | + 'id' => [ 'type' => 'integer' ], | |
| 436 | + 'state' => [ 'type' => 'string' ], | |
| 437 | + 'materialized' => [ 'type' => 'boolean' ], | |
| 438 | + 'progress' => [ 'type' => [ 'object', 'null' ] ] | |
| 439 | + ] | |
| 440 | + ], | |
| 441 | + 'annotations' => self::annotations( false, false, true, 2.0 ) | |
| 442 | + ], | |
| 443 | + [ | |
| 444 | + 'id' => 'betterdocs-pro/get-search-insights', | |
| 445 | + 'label' => __( 'Get search insights', 'betterdocs' ), | |
| 446 | + 'description' => __( 'Read what visitors search for in the knowledge base: the most-used search terms and how often each was searched.', 'betterdocs' ), | |
| 447 | + 'feature' => __( 'Search insights', 'betterdocs' ), | |
| 448 | + 'capability' => 'read_docs_analytics', | |
| 449 | + 'kb_feature' => false, | |
| 450 | + 'input_schema' => [ | |
| 451 | + 'type' => 'object', | |
| 452 | + 'properties' => [ | |
| 453 | + 'limit' => [ | |
| 454 | + 'type' => 'integer', | |
| 455 | + 'description' => __( 'How many top search terms to return (default 20, max 100).', 'betterdocs' ) | |
| 456 | + ] | |
| 457 | + ], | |
| 458 | + 'default' => [] | |
| 459 | + ], | |
| 460 | + 'output_schema' => [ | |
| 461 | + 'type' => 'object', | |
| 462 | + 'properties' => [ | |
| 463 | + 'keywords' => [ 'type' => 'array' ], | |
| 464 | + 'total' => [ 'type' => 'integer' ] | |
| 465 | + ] | |
| 466 | + ], | |
| 467 | + 'annotations' => self::annotations( true, false, true, 1.0 ) | |
| 468 | + ], | |
| 469 | + [ | |
| 470 | + 'id' => 'betterdocs-pro/get-git-sync-status', | |
| 471 | + 'label' => __( 'Get Git sync status', 'betterdocs' ), | |
| 472 | + 'description' => __( 'Report the Git integration configuration and whether it is connected: provider, repository, branch, folder, file naming and auto-sync. Pass a doc id to also get that doc\'s last sync time and status.', 'betterdocs' ), | |
| 473 | + 'feature' => __( 'Git sync', 'betterdocs' ), | |
| 474 | + 'capability' => 'manage_options', | |
| 475 | + 'kb_feature' => false, | |
| 476 | + 'input_schema' => [ | |
| 477 | + 'type' => 'object', | |
| 478 | + 'properties' => [ | |
| 479 | + 'doc_id' => [ | |
| 480 | + 'type' => 'integer', | |
| 481 | + 'description' => __( 'Optional doc id to report per-document sync state for.', 'betterdocs' ) | |
| 482 | + ] | |
| 483 | + ] | |
| 484 | + ], | |
| 485 | + 'output_schema' => [ | |
| 486 | + 'type' => 'object', | |
| 487 | + 'properties' => [ | |
| 488 | + 'enabled' => [ 'type' => 'boolean' ], | |
| 489 | + 'connected' => [ 'type' => 'boolean' ], | |
| 490 | + 'provider' => [ 'type' => 'string' ], | |
| 491 | + 'repository_url' => [ 'type' => 'string' ], | |
| 492 | + 'branch' => [ 'type' => 'string' ], | |
| 493 | + 'docs_directory' => [ 'type' => 'string' ], | |
| 494 | + 'file_naming' => [ 'type' => 'string' ], | |
| 495 | + 'auto_sync' => [ 'type' => 'boolean' ], | |
| 496 | + 'doc' => [ 'type' => [ 'object', 'null' ] ] | |
| 497 | + ] | |
| 498 | + ], | |
| 499 | + 'annotations' => self::annotations( true, false, true, 1.0 ) | |
| 500 | + ], | |
| 501 | + [ | |
| 502 | + 'id' => 'betterdocs-pro/get-related-docs', | |
| 503 | + 'label' => __( 'Get related docs', 'betterdocs' ), | |
| 504 | + 'description' => __( 'Read the saved related-doc suggestions for a doc — the persisted list shown under the article. Reads the cache only; it does not run the AI engine.', 'betterdocs' ), | |
| 505 | + 'feature' => __( 'Related docs', 'betterdocs' ), | |
| 506 | + 'capability' => 'edit_docs', | |
| 507 | + 'kb_feature' => false, | |
| 508 | + 'input_schema' => [ | |
| 509 | + 'type' => 'object', | |
| 510 | + 'properties' => [ | |
| 511 | + 'doc_id' => [ | |
| 512 | + 'type' => 'integer', | |
| 513 | + 'description' => __( 'Doc id to read related suggestions for.', 'betterdocs' ) | |
| 514 | + ] | |
| 515 | + ], | |
| 516 | + 'required' => [ 'doc_id' ] | |
| 517 | + ], | |
| 518 | + 'output_schema' => [ | |
| 519 | + 'type' => 'object', | |
| 520 | + 'properties' => [ | |
| 521 | + 'doc_id' => [ 'type' => 'integer' ], | |
| 522 | + 'related' => [ 'type' => 'array' ], | |
| 523 | + 'generated_at' => [ 'type' => [ 'string', 'integer', 'null' ] ] | |
| 524 | + ] | |
| 525 | + ], | |
| 526 | + 'annotations' => self::annotations( true, false, true, 1.0 ) | |
| 217 | 527 | ] |
| 218 | 528 | ]; |
| 219 | 529 | } |
| 220 | 530 | |
| @@ -301,8 +611,37 @@ | ||
| 301 | 611 | * @param bool $idempotent Whether repeating the call is harmless. |
| 302 | 612 | * @param float $priority Ordering hint; 1.0 for reads, 2.0 for writes. |
| 303 | 613 | * @return array |
| 304 | 614 | */ |
| 615 | + /** | |
| 616 | + * The shape one API reference comes back as. | |
| 617 | + * | |
| 618 | + * Permissive on purpose, like {@see self::knowledge_base_schema()}: the | |
| 619 | + * Abilities API validates output against this, so nothing is `required` and | |
| 620 | + * a Pro build that adds a field must not fail an otherwise-good call. | |
| 621 | + * | |
| 622 | + * @since 4.9.1 | |
| 623 | + * | |
| 624 | + * @return array | |
| 625 | + */ | |
| 626 | + private static function api_reference_schema(): array { | |
| 627 | + return [ | |
| 628 | + 'type' => 'object', | |
| 629 | + 'properties' => [ | |
| 630 | + 'id' => [ 'type' => 'integer' ], | |
| 631 | + 'title' => [ 'type' => 'string' ], | |
| 632 | + 'slug' => [ 'type' => 'string' ], | |
| 633 | + 'status' => [ 'type' => 'string' ], | |
| 634 | + 'permalink' => [ 'type' => 'string' ], | |
| 635 | + 'source' => [ 'type' => 'string' ], | |
| 636 | + 'source_kind' => [ 'type' => 'string' ], | |
| 637 | + 'materialized' => [ 'type' => 'boolean' ], | |
| 638 | + 'summary' => [ 'type' => [ 'object', 'null' ] ], | |
| 639 | + 'operations' => [ 'type' => 'array' ] | |
| 640 | + ] | |
| 641 | + ]; | |
| 642 | + } | |
| 643 | + | |
| 305 | 644 | private static function annotations( bool $read_only, bool $destructive, bool $idempotent, float $priority ): array { |
| 306 | 645 | return [ |
| 307 | 646 | 'readonly' => $read_only, |
| 308 | 647 | 'destructive' => $destructive, |
