schwarzit / api-linter-rules Goto Github PK

Spectral.yml "HTTP verbs should be used to express different actions or functions on a resource. The verb post, put, etc. are missing".
Current rule makes all HTTP methods to be mandatory in API specification. However, APIs with only GET method are also valid.

Hi,

I've installed and configured the Spectral plugin in IntelliJ on macOS as follows:
Ruleset: https://github.com/SchwarzIT/api-linter-rules/blob/main/spectral.yml
Included files: **.yml

The linting fails with the following errors. I've tried an alternate ruleset file as well, unfortunately with the same results:

13:52	Linting failed
			Execution of Spectral failed using the following command: ""/Users/myuser/Library/Application Support/JetBrains/IdeaIC2021.3/plugins/spectral-intellij-plugin/spectralExecutables/spectral-macos" lint --format json --ruleset https://github.com/SchwarzIT/api-linter-rules/blob/main/spectral.yml /var/folders/jy/wp8k1n1d0nx2kqtt6tlfrs5c0000gn/T/5251202261066929309.tmp"
			Error Message:
			Invalid ruleset provided

Can you please look into this? Many thanks in advance!

I’ve noticed that the linter rules currently check examples only at the object level. While this is useful for overall consistency, there are scenarios where property-level example validation would be beneficial. Specifically, I’d like to propose an enhancement that allows to validate examples associated with individual properties within an OpenAPI document.

Use Case: Consider the following situation:

• An API specification contains multiple properties within an object.
• Each property has its own example value.
• Some properties are defined globally and have their own property-specific example attached (e.g. 'createdAt' or 'updatedAt' attributes).

Expected Behavior: I suggest extending the rule to validate examples at both the object level and the property level. This enhancement would provide more granular control over example validation.

Benefits:

• Fine-Grained Validation: Property-level example checks would help maintain consistency within individual properties
• Improved API Quality: By validating property-level examples, we can support to reference properties which are used in multiple object without specify the relevant examples again for each occurrence

Example: Suppose we have an OpenAPI schema like this:

openapi: 3.0.0
info:
  title: My API
  version: 1.0.0
paths:
  /demo:
    get:
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Demo'
components:
  schemas:
    timestamp:
      type: string
      format: date-time
      readOnly: true
      description: >
        This value is auto generated by the API [RFC 3339, section
        5.6/ISO8601](https://www.rfc-editor.org/rfc/rfc3339#section-5.6)
      example: '2022-09-25T10:43:28.000Z'
    Demo:
      type: object
      properties:
        id:
          type: string
          description: ID of the source
          example: ce49715f-784b-45fd-b6c4-56f8435237a2
        createdAt:
          $ref: '#/components/schemas/timestamp'
        updatedAt:
          $ref: '#/components/schemas/timestamp'