Upgrade Growstuff API Schema to OpenAPI 3.0 for GPT Integration

[spencerthayer]

Objective

Convert Growstuff's Swagger 2.0 API schema to OpenAPI 3.0 to facilitate GPT-based application integrations.

Tasks

1. Schema Conversion

Update the schema to OpenAPI 3.0, ensuring compliance with the latest standards. Helpful resources:

• OpenAPI Specification: GitHub repository
• Swagger Editor for validation: https://editor.swagger.io/

2. Enhance Documentation

Include examples and detailed endpoint descriptions. Resources for documentation standards:

• OpenAPI Guide: https://swagger.io/docs/specification/about/

3. Validation

Use tools to ensure the schema's correctness.

• Swagger to OpenAPI Converter: https://converter.swagger.io/

4. Testing

Ensure all endpoints work as expected with the new schema.

5. Deployment

Update deployment processes to reflect schema changes.

Conversion Examples

Swagger 2.0 Example for /crops Endpoint:

swagger: '2.0'
paths:
  /crops:
    get:
      summary: List all crops
      produces:
        - application/json
      responses:
        200:
          description: An array of crops
          schema:
            type: array
            items:
              $ref: '#/definitions/Crop'
definitions:
  Crop:
    type: object
    properties:
      name:
        type: string
      description:
        type: string

Converted OpenAPI 3.0 Example for /crops Endpoint:

openapi: 3.0.0
paths:
  /crops:
    get:
      summary: List all crops
      responses:
        '200':
          description: An array of crops
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Crop'
components:
  schemas:
    Crop:
      type: object
      properties:
        name:
          type: string
        description:
          type: string

Expected Outcome

A compatible OpenAPI 3.0 schema for seamless GPT application integration, enhancing API usability and accessibility.

[CloCkWeRX]

Pull requests welcome for this one.

We use jsonapi-swagger:

https://github.com/Growstuff/growstuff/blob/dev/Gemfile#L22

Should have good test coverage as well under spec/requests/API/*

[spencerthayer]

Awesome. I'll look into it. (As soon as I can create an account.)

[CloCkWeRX]

@CloCkWeRX ➜ /workspaces/growstuff (openapi) $ bundle exec rake rswag:specs:swaggerize
/usr/local/bin/ruby -I/usr/local/rvm/gems/default/gems/rspec-core-3.13.5/lib:/usr/local/rvm/gems/default/gems/rspec-support-3.13.4/lib /usr/local/rvm/gems/default/gems/rspec-core-3.13.5/exe/rspec --pattern spec/requests/\*\*/\*_spec.rb,\ spec/api/\*\*/\*_spec.rb,\ spec/integration/\*\*/\*_spec.rb --format Rswag::Specs::SwaggerFormatter --dry-run --order defined
Generating Swagger docs ...
Run options: include {:focus=>true}

All examples were filtered out; ignoring {:focus=>true}
Swagger doc generated at /workspaces/growstuff/swagger/v1/swagger.yaml

Top 3 slowest examples (0.00002 seconds, 0.2% of total time):
  Crops #create
    0.00001 seconds ./spec/requests/api/v1/crop_request_spec.rb:86
  Plantings with a member GET /members/x/plantings.ics works!
    0.00001 seconds ./spec/requests/plantings_spec.rb:31
  Crops #show 
    0.00001 seconds ./spec/requests/api/v1/crop_request_spec.rb:81

Top 3 slowest example groups:
  Plantings
    0.00031 seconds average (0.00094 seconds / 3 examples) ./spec/requests/plantings_spec.rb:5
  Photos
    0.00022 seconds average (0.00022 seconds / 1 example) ./spec/requests/photos_spec.rb:5
  Seeds
    0.00021 seconds average (0.00021 seconds / 1 example) ./spec/requests/seeds_spec.rb:5

Finished in 0.01012 seconds (files took 9.3 seconds to load)
75 examples, 0 failures

But that didn't do much due to

All examples were filtered out; ignoring {:focus=>true}