LintGPT (AI Rules)

LintGPT lets you write your API style guide in natural language. LintGPT rules are great at enforcing standards that are very difficult to write traditional rules for. For example:

• If a property’s name implies it is a date, it must use datetime or timestamp format.
• GET Responses that return arrays at their root should use some form of pagination.
• 200 response bodies should not be used to return errors. Those must use 4xx.
• Parameter descriptions MUST explain how the client uses the parameter, not what the parameter is. Bad: “the start date” Good: “set this parameter to the earliest date you want to receive records from”.

ruleset:
  - lintgpt:
      v3_standards:
        rules:
         - "All operations should have operationId"
         - "GET requests that have an ID at the end of their path (ie /teams/{teamID}) should define a 404."
         - "Responses that return an array at their root MUST wrap that array in an object. ie {'users': []}"

How to write effective LintGPT rules

Optic had to decide which part of your OpenAPI description each rule applies to. You must be explicit about this in the rule by mentioning operations, property, requests, responses, response headers, path parameters, query parameters, or header parameters.

Good: Response properties should be named in camelCase Bad: Use camelCase

Conditional Rules

LintGPT rules can be set to run on only certain matching patterns. For example if you wanted to make sure every type: number has a minimum and default set, you can write a rule that applies to only numbers.

Good: If a property is a number, it must have a default and minimum set Bad: Number properties must have a default and minimum set

When these rules run, this rule will skip every property that is not a number.

Severity

Optic has different issue levels. LintGPT can return both warn and error level issues. You can set this by using the words should or must in your rule.

Error: All operations must have security defined Warn: `Request property descriptions should be written from the client's point of view. ie "set the earliest date you wish to revive records from" .

Limitations

1. You can't write rules about your API's path structure or how multiple endpoints relate. Right now Optic only knows about one operation at a time.

2. Large Language Models (LLMs) are a new technology that can hallucinate and behave in unpredictable ways. You should test any rules you write work the way you expect before turning them on in production. In our experience once you get the prompt right, rules run consistently. If you cannot get a rule to behave consistently we suggest you turn it off or make it a warning (not error).

3. Optic's ability to debug strange behavior is very limited due to the nature of these rules. We suggest you use them to enforce design principles that are hard to write traditional rules for. If you have any rules that are mission-critical re: gateway extensions, security, etc you probably want to write code rules for those.