OpenAPI Swagger description of Rest endpoints

ernestmarcinko commented 5 months ago

(Reqested via Email by Robert)

Feature Request: OpenAPI Specification Support

Objective: To provide an OpenAPI (Swagger) specification for the Ajax Search Pro REST API, allowing for easier integration, testing, and interaction with third-party services, including AI models like OpenAI's GPT.

Benefits:

Standardized API Documentation: OpenAPI provides a standard way to document APIs, making it easier for developers to understand and use the Ajax Search Pro REST API.

Interactive Documentation: Tools like Swagger UI can generate interactive documentation from OpenAPI specifications, allowing developers to test API endpoints directly from the documentation.

Enhanced Integration: Simplifies the process of connecting Ajax Search Pro with other services and platforms, including AI models and automation tools.

Improved Developer Experience: Reduces the learning curve and development time required for integrating Ajax Search Pro into various applications.

Proposed Implementation:

Define OpenAPI Specification: Create a YAML or JSON file that describes the endpoints, parameters, request bodies, and responses of the Ajax Search Pro REST API. Include detailed descriptions and examples for each endpoint.

Provide Documentation: Host the OpenAPI specification file on the official Ajax Search Pro website or repository. Offer a downloadable version for local use.

Interactive Documentation: Integrate Swagger UI or a similar tool to provide interactive API documentation on the Ajax Search Pro documentation site.

seyfro commented 3 months ago

Thanks for adding this feature! I just gave it a quick try and created a GPT using the default swagger.yaml file for actions. Did not work out of the box yet, mainly because the server URL was missing in the yaml file, so I added

openapi: 3.0.0
servers:
  - url: https://www.mydomain.com
info:

and requests could be made from the GPT. Nevertheless I ran into another issue, that the results were too large for GPT to handle:

{
  "response_data": "ResponseTooLargeError"
}

I then tried to check the REST API docs linked at https://knowledgebase.ajaxsearchpro.com/other/rest-api to see if I can limit the number of responses somehow. Unfortunately the link https://www.postman.com/ernestmarcinko/ajax-search-pro/collection/20902664-665af1b3-c066-479b-9f1b-76d22d95b61a?action=share&creator=20902664 is broken.

ernestmarcinko commented 3 months ago

There is one experiment argument (not yet documented): posts_per_page

Ex.: /wp-json/ajax-search-pro/v0/search?id=1&posts_per_page=10

That should do the trick.

flashjunkie commented 3 months ago

Love this addition, something I've been looking to implement.

We have a range of AI tools for helping our customer to plan lessons for their class, ideally I'd like to be able to have the tools search the website for relevant content and this sounds like the bridge needed to help that (I've had little success with embeddings due to the huge range of content)

Is there a demo or any documentation to assist me in getting this up and running? Many thanks!

Jay - tpet.co.uk

wpdreams / ajax-search-pro-development