Edited api.yaml for style and added option to not sort operations alphabetically

Author: cmilesb

content/develop/ai/langcache/api-reference.md

@@ -5,4 +5,5 @@ layout: apireference
 type: page
 params:
   sourcefile: ./api.yaml
+  sortOperationsAlphabetically: false
 ---

content/develop/ai/langcache/api-reference/api.yaml

@@ -1,14 +1,14 @@
 openapi: 3.0.1
 info:
   title: Redis LangCache Service
-  description: API for managing a Redis LangCache
+  description: API for managing a [Redis LangCache](https://redis.io/docs/latest/develop/ai/langcache/) service.
   contact:
     name: Redis
     email: [email protected]
   version: '1.0'
 tags:
   - name: Cache Entries
-    description: Operations for creating, searching, and deleting cache entries
+    description: Operations for creating, searching, and deleting cache entries.
 servers:
   - url: http://localhost:8080
     description: Generated server URL
@@ -18,6 +18,7 @@ paths:
       tags:
         - Cache Entries
       summary: Search the cache
+      description: Searches the cache for entries that match the prompt and attributes. If no entries are found, this endpoint returns an empty array.
       operationId: search
       parameters:
         - $ref: '#/components/parameters/cacheId'
@@ -68,7 +69,8 @@ paths:
     post:
       tags:
         - Cache Entries
-      summary: Add a new cache entry to the cache
+      summary: Add a new entry to the cache
+      description: Adds an entry to the cache with a prompt and response.
       operationId: set
       parameters:
         - $ref: '#/components/parameters/cacheId'
@@ -118,7 +120,8 @@ paths:
     delete:
       tags:
         - Cache Entries
-      summary: Delete cache entries based on the request parameters
+      summary: Delete multiple cache entries
+      description: Deletes multiple cache entries based on specified attributes. If no attributes are provided, all entries in the cache are deleted.
       operationId: deleteQuery
       parameters:
         - $ref: '#/components/parameters/cacheId'
@@ -169,7 +172,8 @@ paths:
     delete:
       tags:
         - Cache Entries
-      summary: Delete a cache entry by ID
+      summary: Delete a single cache entry
+      description: Deletes a single cache entry by the entry ID.
       operationId: delete
       parameters:
         - $ref: '#/components/parameters/cacheId'
@@ -218,14 +222,14 @@ components:
     cacheId:
       name: cacheId
       in: path
-      description: The ID of the cache
+      description: The cache ID.
       required: true
       schema:
         type: string
     entryId:
       name: entryId
       in: path
-      description: The ID of the cache entry to delete
+      description: The ID of the cache entry to delete.
       required: true
       schema:
         type: string
@@ -237,20 +241,20 @@ components:
       properties:
         prompt:
           type: string
-          description: The prompt to search in the cache
+          description: The prompt to search for in the cache.
           example: How does semantic caching work?
         similarityThreshold:
           minimum: 0
           maximum: 1
           type: number
-          description: The minimum similarity threshold for the cache entry (normalized cosine similarity)
+          description: The minimum similarity threshold for the cache entry (normalized cosine similarity).
           format: float
           example: 0.9
         attributes:
           type: object
           additionalProperties:
             type: string
-          description: Key-value pairs of attributes based on which to filter the cache entries. If multiple attributes are provided, only entries matching all attributes can be returned.
+          description: Key-value pairs of attributes that filter the cache entries. If provided, this endpoint only returns entries that contain all given attributes.
           example:
             language: en
             topic: ai
@@ -264,7 +268,7 @@ components:
           type: array
           items:
             $ref: '#/components/schemas/CacheEntry'
-          description: Array of cache entries matching the search criteria
+          description: Array of cache entries matching the search criteria. This array is empty if no entries match the search criteria.
       description: Response representing the result of a successful cache entries search operation
     CacheEntry:
       required:
@@ -277,27 +281,27 @@ components:
       properties:
         id:
           type: string
-          description: Unique identifier for the cache entry
+          description: Unique identifier for the cache entry.
           example: myIndex:5b84acef3ce360988d1b35adbaaaccb164569b6d79fab04fd888b5fea03fb8f2
         prompt:
           type: string
-          description: The prompt associated with the cache entry
+          description: The prompt associated with the cache entry.
           example: Tell me how semantic caching works
         response:
           type: string
-          description: The response associated with the cache entry
+          description: The response associated with the cache entry.
           example: Semantic caching stores and retrieves data based on meaning, not exact matches.
         attributes:
           type: object
           additionalProperties:
             type: string
-          description: The key-value pairs of attributes that are associated with the cache entry
+          description: The key-value pairs of attributes that are associated with the cache entry.
           example:
             language: en
             topic: ai
         similarity:
           type: number
-          description: The similarity metric used for similarity comparison
+          description: The similarity metric used for similarity comparison.
           format: float
           example: 0.95
       description: A cache entry
@@ -310,22 +314,22 @@ components:
         prompt:
           example: How does semantic caching work?
           type: string
-          description: The entry's prompt
+          description: The prompt for the entry.
         response:
           example: Semantic caching stores and retrieves data based on meaning, not exact matches.
           type: string
-          description: The entry's response
+          description: The response to the prompt for the entry.
         attributes:
           type: object
           additionalProperties:
             type: string
-          description: Key-value pairs of attributes to be associated with the entry, can be used for filtering when searching for entries. All attribute names that can be associated with an entry must be initially defined during the cache creation.
+          description: Key-value pairs of attributes to be associated with the entry. These can be used for filtering when searching for entries. All attribute names that can be associated with an entry must be defined during cache creation.
           example:
             language: en
             topic: ai
         ttlMillis:
           type: integer
-          description: The entry's time-to-live, in milliseconds
+          description: The entry's time-to-live, in milliseconds.
           format: int64
       description: Request to add a cache entry to the cache
     SetEntryResponse:
@@ -335,7 +339,7 @@ components:
       properties:
         entryId:
           type: string
-          description: The ID of the entry that was added to the cache
+          description: The ID of the entry that was added to the cache.
       description: Response representing a successful cache entry addition 
     DeleteEntriesRequest:
       required:
@@ -346,7 +350,7 @@ components:
           type: object
           additionalProperties:
             type: string
-          description: Key-value pairs of attributes based on which to delete cache entries. If multiple attributes are provided, only entries matching all attributes will be deleted.
+          description: Key-value pairs of attributes associated with the cache entries to delete. If provided, this endpoint only deletes entries that contain all given attributes. If not provided, this endpoint deletes all entries in the cache.
           example:
             language: en
             topic: ai
@@ -358,7 +362,7 @@ components:
       properties:
         deletedEntriesCount:
           type: integer
-          description: The number of cache entries successfully deleted
+          description: The number of cache entries successfully deleted.
           format: int64
           example: 42
       description: Response indicating the result of a cache entries deletion operation
@@ -367,15 +371,15 @@ components:
       properties:
         title:
           type: string
-          description: A short, human-readable summary of the problem type
+          description: A short summary of the problem type.
           example: Invalid Request
         status:
           type: integer
           default: 400
-          description: The HTTP status code generated by the origin server for this occurrence of the problem
+          description: The HTTP status code generated by the origin server.
         detail:
           type: string
-          description: A human-readable explanation specific to this occurrence of the problem
+          description: An explanation specific to this problem.
         type:
           $ref: '#/components/schemas/BadRequestErrorUri'
       required:
@@ -391,14 +395,14 @@ components:
       properties:
         title:
           type: string
-          description: A short, human-readable summary of the problem type
+          description: A short summary of the problem type.
         status:
           type: integer
           default: 401
-          description: The HTTP status code generated by the origin server for this occurrence of the problem
+          description: The HTTP status code generated by the origin server.
         detail:
           type: string
-          description: A human-readable explanation specific to this occurrence of the problem
+          description: An explanation specific to this problem.
         type:
           $ref: '#/components/schemas/AuthenticationErrorUri'
       required:
@@ -414,15 +418,15 @@ components:
       properties:
         title:
           type: string
-          description: A short, human-readable summary of the problem type
+          description: A short summary of the problem type.
           example: Unauthorized
         status:
           type: integer
           default: 403
-          description: The HTTP status code generated by the origin server for this occurrence of the problem
+          description: The HTTP status code generated by the origin server.
         detail:
           type: string
-          description: A human-readable explanation specific to this occurrence of the problem
+          description: An explanation specific to this problem.
         type:
           $ref: '#/components/schemas/ForbiddenErrorUri'
       required:
@@ -438,15 +442,15 @@ components:
       properties:
         title:
           type: string
-          description: A short, human-readable summary of the problem type
+          description: A short summary of the problem type.
           example: Service Unavailable
         status:
           type: integer
           default: 503
-          description: The HTTP status code generated by the origin server for this occurrence of the problem
+          description: The HTTP status code generated by the origin server.
         detail:
           type: string
-          description: A human-readable explanation specific to this occurrence of the problem
+          description: An explanation specific to this problem.
         type:
           $ref: '#/components/schemas/ServiceUnavailableErrorUri'
       required:
@@ -466,14 +470,14 @@ components:
       properties:
         title:
           type: string
-          description: A short, human-readable summary of the problem type
+          description: A short summary of the problem type.
         status:
           type: integer
           default: 404
-          description: The HTTP status code generated by the origin server for this occurrence of the problem
+          description: The HTTP status code generated by the origin server.
         detail:
           type: string
-          description: A human-readable explanation specific to this occurrence of the problem
+          description: An explanation specific to this problem.
         type:
           $ref: '#/components/schemas/NotFoundErrorUri'
       required:
@@ -489,14 +493,14 @@ components:
       properties:
         title:
           type: string
-          description: A short, human-readable summary of the problem type
+          description: A short summary of the problem type.
         status:
           type: integer
           default: 500
-          description: The HTTP status code generated by the origin server for this occurrence of the problem
+          description: The HTTP status code generated by the origin server.
         detail:
           type: string
-          description: A human-readable explanation specific to this occurrence of the problem
+          description: An explanation specific to this problem.
         type:
           $ref: '#/components/schemas/InternalServerErrorUri'
       required:

layouts/_default/apireference.html

@@ -6,6 +6,7 @@
 When creating a new API reference page, you can specify these optional params in the front matter:
 - sourcefile: The path to the OpenAPI specification file (YAML or JSON) relative to the page. Default: ./openapi.json
 - backLink: The path to the page to link to in the top left corner. Default: Parent page
+- sortOperationsAlphabetically: Whether to sort the operations alphabetically or use the order defined in the OpenAPI spec. Default: true
 
 Here's what the file structure should look like to use this template:
 <containing-folder>/
@@ -25,6 +26,7 @@
 params:
   sourcefile: ./<spec-file-name> (optional - only specify if not using ./openapi.json)
   backLink: <path-to-page> (optional - only specify if not using the parent page)
+  sortOperationsAlphabetically: <true|false> (optional - default: true)
 ---
 
 Example usage for the Redis Cloud API with all params set:
@@ -36,6 +38,7 @@
 params:
   sourcefile: ./openapi.json
   backLink: operate/rc/api
+  sortOperationsAlphabetically: true
 ---
 -->
 
@@ -106,7 +109,7 @@
             spec-url='{{ .Params.sourcefile | default "./openapi.json" }}'
             scroll-y-offset='#apiReferenceHeader'
             json-sample-expand-level=all
-            sort-operations-alphabetically="true"
+            sort-operations-alphabetically='{{ .Params.sortOperationsAlphabetically | default "true" }}'
             theme='{
                 "rightPanel": {
                     "width": "50%"