From 5adb611c85ac88b800347db728c766bf1be73acd Mon Sep 17 00:00:00 2001 From: rzmk <30333942+rzmk@users.noreply.github.com> Date: Wed, 22 Oct 2025 10:37:22 -0400 Subject: [PATCH] feat(docs): add more endpoints and remove slashes before endpoint names --- .../current_package_list_with_resources.mdx | 24 +++ docs/content/docs/member_list.mdx | 24 +++ .../docs/package_collaborator_list.mdx | 34 ++++ .../package_collaborator_list_for_user.mdx | 28 +++ docs/content/docs/package_list.mdx | 6 +- docs/content/docs/package_search.mdx | 62 ++++++- docs/content/docs/package_show.mdx | 6 +- docs/content/docs/status_show.mdx | 6 +- docs/lib/openapi.yml | 174 ++++++++++++++++-- docs/lib/source.ts | 16 +- 10 files changed, 346 insertions(+), 34 deletions(-) create mode 100644 docs/content/docs/current_package_list_with_resources.mdx create mode 100644 docs/content/docs/member_list.mdx create mode 100644 docs/content/docs/package_collaborator_list.mdx create mode 100644 docs/content/docs/package_collaborator_list_for_user.mdx diff --git a/docs/content/docs/current_package_list_with_resources.mdx b/docs/content/docs/current_package_list_with_resources.mdx new file mode 100644 index 0000000..a520ea7 --- /dev/null +++ b/docs/content/docs/current_package_list_with_resources.mdx @@ -0,0 +1,24 @@ +--- +title: current_package_list_with_resources +full: true +_openapi: + method: POST + route: current_package_list_with_resources + toc: [] + structuredData: + headings: [] + contents: + - content: | + Return a list of the site's datasets (packages) and their resources. + + The list is sorted most-recently-modified first. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +Return a list of the site's datasets (packages) and their resources. + +The list is sorted most-recently-modified first. + + + \ No newline at end of file diff --git a/docs/content/docs/member_list.mdx b/docs/content/docs/member_list.mdx new file mode 100644 index 0000000..e2ef1cc --- /dev/null +++ b/docs/content/docs/member_list.mdx @@ -0,0 +1,24 @@ +--- +title: member_list +full: true +_openapi: + method: POST + route: member_list + toc: [] + structuredData: + headings: [] + contents: + - content: | + Return the members of a group. + + The user must have permission to "get" the group. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +Return the members of a group. + +The user must have permission to "get" the group. + + + \ No newline at end of file diff --git a/docs/content/docs/package_collaborator_list.mdx b/docs/content/docs/package_collaborator_list.mdx new file mode 100644 index 0000000..57735a4 --- /dev/null +++ b/docs/content/docs/package_collaborator_list.mdx @@ -0,0 +1,34 @@ +--- +title: package_collaborator_list +full: true +_openapi: + method: POST + route: package_collaborator_list + toc: [] + structuredData: + headings: [] + contents: + - content: > + Return the list of all collaborators for a given dataset (package). + + + Currently you must be an Admin on the dataset owner organization to + manage collaborators. + + + Note: This action requires the collaborators feature to be enabled + with the + [`ckan.auth.allow_dataset_collaborators`](https://docs.ckan.org/en/2.11/maintaining/configuration.html#ckan-auth-allow-dataset-collaborators) + configuration option. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +Return the list of all collaborators for a given dataset (package). + +Currently you must be an Admin on the dataset owner organization to manage collaborators. + +Note: This action requires the collaborators feature to be enabled with the [`ckan.auth.allow_dataset_collaborators`](https://docs.ckan.org/en/2.11/maintaining/configuration.html#ckan-auth-allow-dataset-collaborators) configuration option. + + + \ No newline at end of file diff --git a/docs/content/docs/package_collaborator_list_for_user.mdx b/docs/content/docs/package_collaborator_list_for_user.mdx new file mode 100644 index 0000000..6a6dadf --- /dev/null +++ b/docs/content/docs/package_collaborator_list_for_user.mdx @@ -0,0 +1,28 @@ +--- +title: package_collaborator_list_for_user +full: true +_openapi: + method: POST + route: package_collaborator_list_for_user + toc: [] + structuredData: + headings: [] + contents: + - content: > + Return the list of all datasets the user is a collaborator in. + + + Note: This action requires the collaborators feature to be enabled + with the + [`ckan.auth.allow_dataset_collaborators`](https://docs.ckan.org/en/2.11/maintaining/configuration.html#ckan-auth-allow-dataset-collaborators) + configuration option. +--- + +{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} + +Return the list of all datasets the user is a collaborator in. + +Note: This action requires the collaborators feature to be enabled with the [`ckan.auth.allow_dataset_collaborators`](https://docs.ckan.org/en/2.11/maintaining/configuration.html#ckan-auth-allow-dataset-collaborators) configuration option. + + + \ No newline at end of file diff --git a/docs/content/docs/package_list.mdx b/docs/content/docs/package_list.mdx index f680178..bcc1f9c 100644 --- a/docs/content/docs/package_list.mdx +++ b/docs/content/docs/package_list.mdx @@ -1,9 +1,9 @@ --- -title: /package_list +title: package_list full: true _openapi: method: POST - route: /package_list + route: package_list toc: [] structuredData: headings: [] @@ -15,4 +15,4 @@ _openapi: This endpoint lists CKAN resources. - \ No newline at end of file + \ No newline at end of file diff --git a/docs/content/docs/package_search.mdx b/docs/content/docs/package_search.mdx index def631e..4a71c1c 100644 --- a/docs/content/docs/package_search.mdx +++ b/docs/content/docs/package_search.mdx @@ -1,18 +1,72 @@ --- -title: /package_search +title: package_search full: true _openapi: method: POST - route: /package_search + route: package_search toc: [] structuredData: headings: [] contents: - - content: Searches for packages satisfying a given search criteria. + - content: > + Searches for packages satisfying a given search criteria. + + + This action accepts Solr search query parameters (details below), and + returns a dictionary of results, including dictized datasets that + match the search criteria, a search count, and also facet information. + + + Solr Parameters: + + + For more in depth treatment of each parameter, please read the [Solr + Documentation](https://solr.apache.org/guide/6_6/common-query-parameters.html). + + + This action accepts a subset of Solr's search query parameters. + + + The following advanced Solr parameters are supported as well. Note + that some of these are only available on particular Solr versions. See + Solr’s dismax and edismax documentation for further details on them: + + + `qf`, `wt`, `bf`, `boost`, `tie`, `defType`, `mm` + + + Examples: + + + - `q=flood` datasets containing the word *flood*, *floods*, or + *flooding* + + - `fq=tags:economy` datasets with the tag *economy* + + - `facet.field=["tags"] facet.limit=10 rows=0` top 10 tags --- {/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */} Searches for packages satisfying a given search criteria. - \ No newline at end of file +This action accepts Solr search query parameters (details below), and returns a dictionary of results, including dictized datasets that match the search criteria, a search count, and also facet information. + +Solr Parameters: + +For more in depth treatment of each parameter, please read the [Solr Documentation](https://solr.apache.org/guide/6_6/common-query-parameters.html). + +This action accepts a subset of Solr's search query parameters. + +The following advanced Solr parameters are supported as well. Note that some of these are only available on particular Solr versions. See Solr’s dismax and edismax documentation for further details on them: + +`qf`, `wt`, `bf`, `boost`, `tie`, `defType`, `mm` + +Examples: + +- `q=flood` datasets containing the word *flood*, *floods*, or *flooding* +- `fq=tags:economy` datasets with the tag *economy* +- `facet.field=["tags"] facet.limit=10 rows=0` top 10 tags + + + \ No newline at end of file diff --git a/docs/content/docs/package_show.mdx b/docs/content/docs/package_show.mdx index aa0293e..efc0fd1 100644 --- a/docs/content/docs/package_show.mdx +++ b/docs/content/docs/package_show.mdx @@ -1,9 +1,9 @@ --- -title: /package_show +title: package_show full: true _openapi: method: POST - route: /package_show + route: package_show toc: [] structuredData: headings: [] @@ -15,4 +15,4 @@ _openapi: Return the metadata of a dataset and its resources. - \ No newline at end of file + \ No newline at end of file diff --git a/docs/content/docs/status_show.mdx b/docs/content/docs/status_show.mdx index b98d56a..9752546 100644 --- a/docs/content/docs/status_show.mdx +++ b/docs/content/docs/status_show.mdx @@ -1,9 +1,9 @@ --- -title: /status_show +title: status_show full: true _openapi: method: GET - route: /status_show + route: status_show toc: [] structuredData: headings: [] @@ -15,4 +15,4 @@ _openapi: This endpoint shows information about the CKAN instance. - \ No newline at end of file + \ No newline at end of file diff --git a/docs/lib/openapi.yml b/docs/lib/openapi.yml index 4d1c78f..ea1b8f1 100644 --- a/docs/lib/openapi.yml +++ b/docs/lib/openapi.yml @@ -26,10 +26,99 @@ servers: domain: default: 'demo.ckan.org' paths: - '/status_show': + 'current_package_list_with_resources': + post: + operationId: current_package_list_with_resources + summary: current_package_list_with_resources + description: | + Return a list of the site's datasets (packages) and their resources. + + The list is sorted most-recently-modified first. + requestBody: + required: false + content: + application/json: + schema: + type: object + properties: + limit: + type: integer + description: "if given, the list of datasets will be broken into pages of at most `limit` datasets per page and only one page will be returned at a time" + offset: + type: integer + description: "when `limit` is given, the offset to start returning packages from" + 'member_list': + post: + operationId: member_list + summary: member_list + description: | + Return the members of a group. + + The user must have permission to "get" the group. + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + id: + type: string + description: the id or name of the group + object_type: + type: string + description: "restrict the members returned to those of a given type, e.g. `'user'` or `'package'` (default: `None`)" + capacity: + type: string + description: "restrict the members returned to those with a given capacity, e.g. `'member'`, `'editor'`, `'admin'`, `'public'`, `'private'` (optional, default: `None`)" + 'package_collaborator_list': + post: + operationId: package_collaborator_list + summary: package_collaborator_list + description: | + Return the list of all collaborators for a given dataset (package). + + Currently you must be an Admin on the dataset owner organization to manage collaborators. + + Note: This action requires the collaborators feature to be enabled with the [`ckan.auth.allow_dataset_collaborators`](https://docs.ckan.org/en/2.11/maintaining/configuration.html#ckan-auth-allow-dataset-collaborators) configuration option. + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + id: + type: string + description: the id or name of the dataset + capacity: + type: string + description: if provided, only the users with this capacity are returned + 'package_collaborator_list_for_user': + post: + operationId: package_collaborator_list_for_user + summary: package_collaborator_list_for_user + description: | + Return the list of all datasets the user is a collaborator in. + + Note: This action requires the collaborators feature to be enabled with the [`ckan.auth.allow_dataset_collaborators`](https://docs.ckan.org/en/2.11/maintaining/configuration.html#ckan-auth-allow-dataset-collaborators) configuration option. + requestBody: + required: true + content: + application/json: + schema: + type: object + properties: + id: + type: string + description: the id or name of the user + capacity: + type: string + description: if provided, only datasets where the user has this capacity are returned + 'status_show': get: - operationId: /status_show - summary: /status_show + operationId: status_show + summary: status_show description: This endpoint shows information about the CKAN instance. x-codeSamples: - lang: rust @@ -54,10 +143,10 @@ paths: Ok(()) } - '/package_list': + 'package_list': post: - operationId: /package_list - summary: /package_list + operationId: package_list + summary: package_list description: This endpoint lists CKAN resources. requestBody: required: false @@ -100,10 +189,10 @@ paths: Ok(()) } - '/package_show': + 'package_show': post: - operationId: /package_show - summary: /package_show + operationId: package_show + summary: package_show description: Return the metadata of a dataset and its resources. requestBody: required: true @@ -150,11 +239,30 @@ paths: Ok(()) } - '/package_search': + 'package_search': post: - operationId: /package_search - summary: /package_search - description: Searches for packages satisfying a given search criteria. + operationId: package_search + summary: package_search + description: | + Searches for packages satisfying a given search criteria. + + This action accepts Solr search query parameters (details below), and returns a dictionary of results, including dictized datasets that match the search criteria, a search count, and also facet information. + + Solr Parameters: + + For more in depth treatment of each parameter, please read the [Solr Documentation](https://solr.apache.org/guide/6_6/common-query-parameters.html). + + This action accepts a subset of Solr's search query parameters. + + The following advanced Solr parameters are supported as well. Note that some of these are only available on particular Solr versions. See Solr’s dismax and edismax documentation for further details on them: + + `qf`, `wt`, `bf`, `boost`, `tie`, `defType`, `mm` + + Examples: + + - `q=flood` datasets containing the word *flood*, *floods*, or *flooding* + - `fq=tags:economy` datasets with the tag *economy* + - `facet.field=["tags"] facet.limit=10 rows=0` top 10 tags requestBody: required: false content: @@ -168,6 +276,46 @@ paths: fq: type: string description: "any filter queries to apply. Note: `+site_id:{ckan_site_id}` is added to this string prior to the query being executed." + fq_list: + type: array + items: + type: string + description: additional filter queries to apply. + sort: + type: string + description: "sorting of the search results. Default: 'score desc, metadata_modified desc'. As per the Solr documentation, this is a comma-separated string of field names and sort-orderings." + rows: + type: integer + description: "the maximum number of matching rows (datasets) to return. (default: 10, upper limit: 1000 unless set in site's configuration `ckan.search.rows_max`)" + start: + type: integer + description: the offset in the complete result for where the set of returned datasets should begin. + facet: + type: boolean + description: "whether to enable faceted results. Default: `True`" + facet.mincount: + type: integer + description: the minimum counts for facet fields should be included in the results. + facet.limit: + type: integer + description: the maximum number of values the facet fields return. A negative value means unlimited. This can be set instance-wide with the [search.facets.limit](https://docs.ckan.org/en/2.11/maintaining/configuration.html#search-facets-limit) config option. Default is 50. + facet.field: + type: array + items: + type: string + description: the fields to facet upon. Default empty. If empty, then the returned facet information is empty. + include_drafts: + type: boolean + description: "if `True`, draft datasets will be included in the results. A user will only be returned their own draft datasets, and a sysadmin will be returned all draft datasets. Optional, the default is `False`." + include_deleted: + type: boolean + description: "if `True`, deleted datasets will be included in the results (site configuration `ckan.search.remove_deleted_packages` must be set to `False`). Optional, the default is `False`." + include_private: + type: boolean + description: "if `True`, private datasets will be included in the results. Only private datasets from the user’s organizations will be returned and sysadmins will be returned all private datasets. Optional, the default is `False`." + use_default_schema: + type: boolean + description: "use default package schema instead of a custom schema defined with an IDatasetForm plugin (default: `False`)" x-codeSamples: - lang: rust label: Rust SDK (ckanaction) example diff --git a/docs/lib/source.ts b/docs/lib/source.ts index 3bf329a..fbb965f 100644 --- a/docs/lib/source.ts +++ b/docs/lib/source.ts @@ -1,26 +1,26 @@ -import { docs } from '@/.source'; -import { type InferPageType, loader } from 'fumadocs-core/source'; -import { lucideIconsPlugin } from 'fumadocs-core/source/lucide-icons'; -import { openapiPlugin } from 'fumadocs-openapi/server'; +import { type InferPageType, loader } from "fumadocs-core/source"; +import { lucideIconsPlugin } from "fumadocs-core/source/lucide-icons"; +import { openapiPlugin } from "fumadocs-openapi/server"; +import { docs } from "@/.source"; // See https://fumadocs.dev/docs/headless/source-api for more info export const source = loader({ - baseUrl: '/docs', + baseUrl: "/docs", source: docs.toFumadocsSource(), plugins: [lucideIconsPlugin(), openapiPlugin()], }); export function getPageImage(page: InferPageType) { - const segments = [...page.slugs, 'image.png']; + const segments = [...page.slugs, "image.png"]; return { segments, - url: `/og/docs/${segments.join('/')}`, + url: `/og/docs/${segments.join("/")}`, }; } export async function getLLMText(page: InferPageType) { - const processed = await page.data.getText('processed'); + const processed = await page.data.getText("processed"); return `# ${page.data.title} (${page.url})