Skip to content

armgit / spree

Public Imported from GitHub
0

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.

Add API documentation for new Posts endpoints (#13054)

Damian Legawiec57149cfbdf59
diff --git a/.claude/settings.local.json b/.claude/settings.local.json
index 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.yaml
index 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
+ - attributes
Product:
type: object
title: Product