Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[BUG] vacuum reports tag error for allowed use case #215

Closed
spacether opened this issue Dec 20, 2022 · 3 comments
Closed

[BUG] vacuum reports tag error for allowed use case #215

spacether opened this issue Dec 20, 2022 · 3 comments

Comments

@spacether
Copy link

spacether commented Dec 20, 2022 •
edited

Spec:

openapi: 3.0.1
info:
  title: Harbor API
  description: These APIs provide services for manipulating Harbor project.
  version: "2.0"
servers:
 - url: https://{env}-[URL]
   description: 'Harbor Server'
   variables:
     env:
      enum:
        - 'preprod'
        - 'prod'
      default: 'preprod'
security:
- basic: []
paths:
  /projects/{project_name}/repositories/{repository_name}/artifacts/{reference}/tags:
    get:
      tags:
      - artifact
      summary: List tags
      description: List tags of the specific artifact
      operationId: listTags
      parameters:
      - name: X-Request-Id
        in: header
        description: An unique ID for the request
        schema:
          minLength: 1
          type: string
      - name: project_name
        in: path
        description: The name of the project
        required: true
        schema:
          type: string
      - name: repository_name
        in: path
        description: The name of the repository. If it contains slash, encode it with
          URL encoding. e.g. a/b -> a%252Fb
        required: true
        schema:
          type: string
      - name: reference
        in: path
        description: The reference of the artifact, can be digest or tag
        required: true
        schema:
          type: string
      - name: q
        in: query
        description: Query string to query resources. Supported query patterns are
          "exact match(k=v)", "fuzzy match(k=~v)", "range(k=[min~max])", "list with
          union releationship(k={v1 v2 v3})" and "list with intersetion relationship(k=(v1
          v2 v3))". The value of range and list can be string(enclosed by " or '),
          integer or time(in format "2020-04-09 02:36:00"). All of these query patterns
          should be put in the query string "q=xxx" and splitted by ",". e.g. q=k1=v1,k2=~v2,k3=[min~max]
        schema:
          type: string
      - name: sort
        in: query
        description: Sort the resource list in ascending or descending order. e.g.
          sort by field1 in ascending orderr and field2 in descending order with "sort=field1,-field2"
        schema:
          type: string
      - name: page
        in: query
        description: The page number
        schema:
          type: integer
          format: int64
          default: 1
      - name: page_size
        in: query
        description: The size of per page
        schema:
          maximum: 100
          type: integer
          format: int64
          default: 10
      - name: with_signature
        in: query
        description: Specify whether the signature is included inside the returning
          tags
        schema:
          type: boolean
          default: false
      - name: with_immutable_status
        in: query
        description: Specify whether the immutable status is included inside the returning
          tags
        schema:
          type: boolean
          default: false
      responses:
        200:
          description: Success
          headers:
            X-Total-Count:
              description: The total count of tags
              schema:
                type: integer
            Link:
              description: Link refers to the previous page and next page
              schema:
                type: string
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Tag'
        400:
          description: Bad request
          headers:
            X-Request-Id:
              description: The ID of the corresponding request for the response
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        401:
          description: Unauthorized
          headers:
            X-Request-Id:
              description: The ID of the corresponding request for the response
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        403:
          description: Forbidden
          headers:
            X-Request-Id:
              description: The ID of the corresponding request for the response
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        404:
          description: Not found
          headers:
            X-Request-Id:
              description: The ID of the corresponding request for the response
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        500:
          description: Internal server error
          headers:
            X-Request-Id:
              description: The ID of the corresponding request for the response
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
    post:
      tags:
      - artifact
      summary: Create tag
      description: Create a tag for the specified artifact
      operationId: createTag
      parameters:
      - name: X-Request-Id
        in: header
        description: An unique ID for the request
        schema:
          minLength: 1
          type: string
      - name: project_name
        in: path
        description: The name of the project
        required: true
        schema:
          type: string
      - name: repository_name
        in: path
        description: The name of the repository. If it contains slash, encode it with
          URL encoding. e.g. a/b -> a%252Fb
        required: true
        schema:
          type: string
      - name: reference
        in: path
        description: The reference of the artifact, can be digest or tag
        required: true
        schema:
          type: string
      requestBody:
        description: The JSON object of tag.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Tag'
        required: true
      responses:
        201:
          description: Created
          headers:
            X-Request-Id:
              description: The ID of the corresponding request for the response
              schema:
                type: string
            Location:
              description: The location of the resource
              schema:
                type: string
        400:
          description: Bad request
          headers:
            X-Request-Id:
              description: The ID of the corresponding request for the response
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        401:
          description: Unauthorized
          headers:
            X-Request-Id:
              description: The ID of the corresponding request for the response
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        403:
          description: Forbidden
          headers:
            X-Request-Id:
              description: The ID of the corresponding request for the response
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        404:
          description: Not found
          headers:
            X-Request-Id:
              description: The ID of the corresponding request for the response
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        405:
          description: Method not allowed
          headers:
            X-Request-Id:
              description: The ID of the corresponding request for the response
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        409:
          description: Conflict
          headers:
            X-Request-Id:
              description: The ID of the corresponding request for the response
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
        500:
          description: Internal server error
          headers:
            X-Request-Id:
              description: The ID of the corresponding request for the response
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Errors'
      x-codegen-request-body-name: tag
components:
  securitySchemes:
    basic:
      type: http
      scheme: basic
  schemas:
    Errors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
      description: The error array that describe the errors got during the handling
        of request
    Error:
      type: object
      properties:
        code:
          type: string
          description: The error code
        message:
          type: string
          description: The error message
      description: a model for all the error response coming from harbor
    Tag:
      type: object
      properties:
        id:
          type: integer
          description: The ID of the tag
          format: int64
        repository_id:
          type: integer
          description: The ID of the repository that the tag belongs to
          format: int64
        artifact_id:
          type: integer
          description: The ID of the artifact that the tag attached to
          format: int64
        name:
          type: string
          description: The name of the tag
        push_time:
          type: string
          description: The push time of the tag
          format: date-time
        pull_time:
          type: string
          description: The latest pull time of the tag
          format: date-time
        immutable:
          type: boolean
          description: The immutable status of the tag
          x-omitempty: false
        signed:
          type: boolean
          description: The attribute indicates whether the tag is signed or not
          x-omitempty: false

vacuum says the lack of tags at the top level of the spec is an error:
Operation tags must be defined in global tags.

But that's not true per the openapi spec:
spec.tags: Not all tags that are used by the [Operation Object](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique.
@daveshanley
Copy link
Owner

This rule (https://quobix.com/vacuum/rules/tags/operation-tag-defined/) is based on this rule from spectral: https://meta.stoplight.io/docs/spectral/4dec24461f3af-open-api-rules#operation-tag-defined

It's more of an opinion rather than anything. If there are tags defined globally, why are they not used? its the same as orphaned components/schemas.

I don't think this is a bug, but I would be OK with dropping it to a warning by default, it's an opinion being expressed (rather harshly) but still, it's taking a stand on clean/tuned specs.

@spacether
Copy link
Author

spacether commented Dec 20, 2022 •
edited

Thanks for explaining the logic, a warning would be preferred as the spec does not specify that root level tags MUST or SHALL include all operation tags

daveshanley added a commit that referenced this issue Dec 21, 2022
@daveshanley
update: dropped rule operatrionTagDefined to warning from error #215
b7dea02 
It's not technically an error, but it is bad design. Compensating by reducing serverity of the rule to not bash it too hard in quality results.

Signed-off-by: Dave Shanley <dave@quobix.com>
daveshanley added a commit that referenced this issue Dec 21, 2022
@daveshanley
update: dropped rule operatrionTagDefined to warning from error #215
36c567e 
It's not technically an error, but it is bad design. Compensating by reducing serverity of the rule to not bash it too hard in quality results.

Signed-off-by: Dave Shanley <dave@quobix.com>
@daveshanley
Copy link
Owner

Docs have been updated: https://quobix.com/vacuum/rules/tags/operation-tag-defined/
Rule severity is reflected in v0.0.46 of vacuum.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@daveshanley @spacether