Open Source Platform for DTC, B2B Commerce, Marketplaces & Omnichannel. REST APIs, TypeScript SDKs, and production-ready Next.js storefront. Self-host it. Own your data. No vendor lock-in. Zero platform fees.
Ruby b2b-commercee-commerceecommerceecommerce-apiecommerce-frameworkecommerce-platformheadlessheadless-commerceheadless-ecommercemarketplacemulti-tenantmulti-vendormulti-vendor-ecommerceopen-sourcespree-commerce
Add API documentation for new Posts endpoints (#13054)
Damian Legawiec57149cfbdf59
diff --git a/.claude/settings.local.json b/.claude/settings.local.jsonindex a1b6bef4a6..79b0688bf4 100644--- a/.claude/settings.local.json+++ b/.claude/settings.local.json@@ -8,7 +8,9 @@"Bash(bundle exec rails c:*)","Bash(ruby test:*)","Bash(mv:*)",- "Bash(bundle exec rails:*)"+ "Bash(bundle exec rails:*)",+ "Bash(curl:*)",+ "Bash(bundle exec rake:*)"],"deny": []}diff --git a/docs/api-reference/storefront.yaml b/docs/api-reference/storefront.yamlindex dac7a6315c..5695cc2e21 100644--- a/docs/api-reference/storefront.yaml+++ b/docs/api-reference/storefront.yaml@@ -1378,6 +1378,294 @@ paths:$ref: '#/components/responses/Policy''404':$ref: '#/components/responses/404NotFound'+ /api/v2/storefront/posts:+ get:+ summary: List all Posts+ description: 'Returns a list of published Posts. This endpoint is only available in Spree 5.2 or later.'+ tags:+ - Posts+ operationId: posts-list+ parameters:+ - $ref: '#/components/parameters/FilterByIds'+ - in: query+ name: 'filter[title]'+ schema:+ type: string+ example: 'Hello World'+ description: Filter Posts by title+ - in: query+ name: 'filter[post_category_id]'+ schema:+ type: string+ example: '1'+ description: Filter Posts by Post Category ID+ - in: query+ name: 'filter[post_category_slug]'+ schema:+ type: string+ example: 'news'+ description: Filter Posts by Post Category slug+ - $ref: '#/components/parameters/PageParam'+ - $ref: '#/components/parameters/PerPageParam'+ - in: query+ name: sort+ schema:+ type: string+ enum: ['id', '-id', 'title', '-title', 'published_at', '-published_at', 'created_at', '-created_at', 'updated_at', '-updated_at']+ example: '-published_at'+ description: 'Sort posts by attribute. Prefix with "-" for descending order. Available options: id, title, published_at, created_at, updated_at'+ - in: query+ name: include+ schema:+ type: string+ example: 'post_category'+ description: 'Include related resources (available: post_category)'+ responses:+ '200':+ description: Success+ content:+ application/json:+ schema:+ type: object+ properties:+ data:+ type: array+ items:+ $ref: '#/components/schemas/Post'+ meta:+ $ref: '#/components/schemas/ListMeta'+ links:+ $ref: '#/components/schemas/ListLinks'+ examples:+ success:+ value:+ data:+ - id: '1'+ type: 'post'+ attributes:+ title: 'Hello World'+ slug: 'hello-world'+ published_at: '2025-08-11T21:03:00.000Z'+ meta_title: ''+ meta_description: ''+ created_at: '2025-08-11T21:03:00.128Z'+ updated_at: '2025-08-27T10:09:23.007Z'+ excerpt: null+ content: 'This is a test post'+ content_html: '<div class="trix-content">\n <div>This is a test post</div>\n</div>\n'+ description: 'This is a test post'+ shortened_description: 'This is a test post'+ author_name: 'Spree Admin'+ post_category_title: 'News'+ tags: []+ image_url: null+ relationships:+ post_category:+ data:+ id: '3'+ type: 'post_category'+ meta:+ count: 1+ total_count: 1+ total_pages: 1+ links:+ self: 'http://localhost:3000/api/v2/storefront/posts'+ next: 'http://localhost:3000/api/v2/storefront/posts?page=1'+ prev: 'http://localhost:3000/api/v2/storefront/posts?page=1'+ last: 'http://localhost:3000/api/v2/storefront/posts?page=1'+ first: 'http://localhost:3000/api/v2/storefront/posts?page=1'+ '/api/v2/storefront/posts/{id}':+ get:+ summary: Retrieve a Post+ description: 'Returns the details of a specified Post. You can use either the post slug or ID. This endpoint is only available in Spree 5.2 or later.'+ tags:+ - Posts+ operationId: show-post+ parameters:+ - name: id+ in: path+ required: true+ schema:+ type: string+ example: 'hello-world'+ description: 'Post slug or ID'+ - in: query+ name: include+ schema:+ type: string+ example: 'post_category'+ description: 'Include related resources (available: post_category)'+ responses:+ '200':+ description: Success+ content:+ application/json:+ schema:+ type: object+ properties:+ data:+ $ref: '#/components/schemas/Post'+ examples:+ success:+ value:+ data:+ id: '1'+ type: 'post'+ attributes:+ title: 'Hello World'+ slug: 'hello-world'+ published_at: '2025-08-11T21:03:00.000Z'+ meta_title: ''+ meta_description: ''+ created_at: '2025-08-11T21:03:00.128Z'+ updated_at: '2025-08-27T10:09:23.007Z'+ excerpt: null+ content: 'This is a test post'+ content_html: '<div class="trix-content">\n <div>This is a test post</div>\n</div>\n'+ description: 'This is a test post'+ shortened_description: 'This is a test post'+ author_name: 'Spree Admin'+ post_category_title: 'News'+ tags: []+ image_url: null+ relationships:+ post_category:+ data:+ id: '3'+ type: 'post_category'+ '404':+ $ref: '#/components/responses/404NotFound'+ /api/v2/storefront/post_categories:+ get:+ summary: List all Post Categories+ description: 'Returns a list of Post Categories. This endpoint is only available in Spree 5.2 or later.'+ tags:+ - Post Categories+ operationId: post-categories-list+ parameters:+ - $ref: '#/components/parameters/FilterByIds'+ - in: query+ name: 'filter[title]'+ schema:+ type: string+ example: 'News'+ description: Filter Post Categories by title+ - $ref: '#/components/parameters/PageParam'+ - $ref: '#/components/parameters/PerPageParam'+ - in: query+ name: sort+ schema:+ type: string+ enum: ['id', '-id', 'title', '-title', 'created_at', '-created_at', 'updated_at', '-updated_at']+ example: 'title'+ description: 'Sort post categories by attribute. Prefix with "-" for descending order. Available options: id, title, created_at, updated_at'+ responses:+ '200':+ description: Success+ content:+ application/json:+ schema:+ type: object+ properties:+ data:+ type: array+ items:+ $ref: '#/components/schemas/PostCategory'+ meta:+ $ref: '#/components/schemas/ListMeta'+ links:+ $ref: '#/components/schemas/ListLinks'+ examples:+ success:+ value:+ data:+ - id: '1'+ type: 'post_category'+ attributes:+ title: 'Resources'+ slug: 'resources'+ created_at: '2025-08-11T20:58:24.354Z'+ updated_at: '2025-08-11T20:58:24.354Z'+ description: null+ relationships: {}+ - id: '2'+ type: 'post_category'+ attributes:+ title: 'Articles'+ slug: 'articles'+ created_at: '2025-08-11T20:58:24.365Z'+ updated_at: '2025-08-11T20:58:24.365Z'+ description: null+ relationships: {}+ - id: '3'+ type: 'post_category'+ attributes:+ title: 'News'+ slug: 'news'+ created_at: '2025-08-11T20:58:24.375Z'+ updated_at: '2025-08-11T20:58:24.375Z'+ description: null+ relationships: {}+ meta:+ count: 3+ total_count: 3+ total_pages: 1+ links:+ self: 'http://localhost:3000/api/v2/storefront/post_categories'+ next: 'http://localhost:3000/api/v2/storefront/post_categories?page=1'+ prev: 'http://localhost:3000/api/v2/storefront/post_categories?page=1'+ last: 'http://localhost:3000/api/v2/storefront/post_categories?page=1'+ first: 'http://localhost:3000/api/v2/storefront/post_categories?page=1'+ '/api/v2/storefront/post_categories/{id}':+ get:+ summary: Retrieve a Post Category+ description: 'Returns the details of a specified Post Category, including related posts. You can use either the category slug or ID. This endpoint is only available in Spree 5.2 or later.'+ tags:+ - Post Categories+ operationId: show-post-category+ parameters:+ - name: id+ in: path+ required: true+ schema:+ type: string+ example: 'news'+ description: 'Post Category slug or ID'+ - in: query+ name: include+ schema:+ type: string+ example: 'posts'+ description: 'Include related resources (available: posts)'+ responses:+ '200':+ description: Success+ content:+ application/json:+ schema:+ type: object+ properties:+ data:+ $ref: '#/components/schemas/PostCategory'+ examples:+ success:+ value:+ data:+ id: '3'+ type: 'post_category'+ attributes:+ title: 'News'+ slug: 'news'+ created_at: '2025-08-11T20:58:24.375Z'+ updated_at: '2025-08-11T20:58:24.375Z'+ description: null+ relationships:+ posts:+ data:+ - id: '1'+ type: 'post'+ '404':+ $ref: '#/components/responses/404NotFound'/api/v2/storefront/taxons:get:description: 'Returns a list of Taxons. [Read more about Taxons](/developer/core-concepts/products#taxons-and-taxonomies)'@@ -3082,6 +3370,175 @@ components:- id- type- attributes+ Post:+ type: object+ title: Post+ description: 'Post represents a blog post or news article that can be displayed on the storefront.'+ properties:+ id:+ type: string+ example: '1'+ type:+ type: string+ default: post+ attributes:+ type: object+ properties:+ title:+ type: string+ example: Hello World+ description: Title of the post+ slug:+ type: string+ example: hello-world+ description: URL-friendly identifier for the post+ published_at:+ type: string+ format: date-time+ example: '2025-08-11T21:03:00.000Z'+ description: Date and time when the post was published+ nullable: true+ meta_title:+ type: string+ example: ''+ description: SEO meta title+ nullable: true+ meta_description:+ type: string+ example: ''+ description: SEO meta description+ nullable: true+ created_at:+ $ref: '#/components/schemas/Timestamp'+ updated_at:+ $ref: '#/components/schemas/Timestamp'+ excerpt:+ type: string+ example: null+ description: Short excerpt of the post content+ nullable: true+ content:+ type: string+ example: This is a test post+ description: Plain text content of the post+ nullable: true+ content_html:+ type: string+ example: "<div class=\"trix-content\">\n <div>This is a test post</div>\n</div>\n"+ description: HTML formatted content of the post+ nullable: true+ description:+ type: string+ example: This is a test post+ description: Description of the post+ nullable: true+ shortened_description:+ type: string+ example: This is a test post+ description: Shortened description of the post+ nullable: true+ author_name:+ type: string+ example: Spree Admin+ description: Name of the post author+ nullable: true+ post_category_title:+ type: string+ example: News+ description: Title of the associated post category+ nullable: true+ tags:+ type: array+ items:+ type: string+ example: []+ description: List of tags associated with the post+ image_url:+ type: string+ example: null+ description: URL of the post's featured image+ nullable: true+ relationships:+ type: object+ properties:+ post_category:+ type: object+ properties:+ data:+ type: object+ properties:+ id:+ type: string+ example: '3'+ type:+ type: string+ example: post_category+ required:+ - title+ - slug+ - created_at+ - updated_at+ required:+ - id+ - type+ - attributes+ PostCategory:+ type: object+ title: Post Category+ description: 'Post Category represents a category for organizing blog posts or news articles.'+ properties:+ id:+ type: string+ example: '1'+ type:+ type: string+ default: post_category+ attributes:+ type: object+ properties:+ title:+ type: string+ example: News+ description: Title of the post category+ slug:+ type: string+ example: news+ description: URL-friendly identifier for the post category+ created_at:+ $ref: '#/components/schemas/Timestamp'+ updated_at:+ $ref: '#/components/schemas/Timestamp'+ description:+ type: string+ example: null+ description: Description of the post category+ nullable: true+ relationships:+ type: object+ properties:+ posts:+ type: object+ properties:+ data:+ type: array+ items:+ type: object+ properties:+ id:+ type: string+ example: '1'+ type:+ type: string+ example: post+ required:+ - title+ - slug+ - created_at+ - updated_at+ required:+ - id+ - type+ - attributesProduct:type: objecttitle: Product