Politecnico di Torino · API Governance Rules

Politecnico di Torino API Rules

Spectral linting rules defining API design standards and conventions for Politecnico di Torino.

6 Rules error 1 warn 4 info 1
View Rules File View on GitHub

Rule Categories

polito

Rules

warn
polito-openapi-3
Specification should declare OpenAPI 3.0.x.
$.openapi
error
polito-servers-defined
At least one server URL must be defined.
$.servers
warn
polito-server-host
Servers should point at the app.didattica.polito.it host.
$.servers[*].url
warn
polito-operation-tags
Every operation should carry at least one tag.
$.paths[*][get,post,put,patch,delete]
warn
polito-operation-id
Operations should declare an operationId.
$.paths[*][get,post,put,patch,delete]
info
polito-summary-present
Operations should include a human summary.
$.paths[*][get,post,put,patch,delete]

Spectral Ruleset

Raw ↑ 
extends:
  - spectral:oas
formats:
  - oas3
documentationUrl: https://github.com/polito/api-spec
rules:
  # PoliTO specs are authored in TypeSpec and target OpenAPI 3.0.
  polito-openapi-3:
    description: Specification should declare OpenAPI 3.0.x.
    severity: warn
    given: $.openapi
    then:
      function: pattern
      functionOptions:
        match: "^3\\.0\\."

  # Both PoliTO APIs publish the official production + mock servers.
  polito-servers-defined:
    description: At least one server URL must be defined.
    severity: error
    given: $.servers
    then:
      function: length
      functionOptions:
        min: 1

  polito-server-host:
    description: Servers should point at the app.didattica.polito.it host.
    severity: warn
    given: $.servers[*].url
    then:
      function: pattern
      functionOptions:
        match: "app\\.didattica\\.polito\\.it"

  # Operations are tagged by domain (Exams, Bookings, Courses, etc.).
  polito-operation-tags:
    description: Every operation should carry at least one tag.
    severity: warn
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: tags
      function: truthy

  # PoliTO uses generated operationIds of the form Group_operationName.
  polito-operation-id:
    description: Operations should declare an operationId.
    severity: warn
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: operationId
      function: truthy

  # Bilingual (IT/EN) summaries are the convention in this spec.
  polito-summary-present:
    description: Operations should include a human summary.
    severity: info
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: summary
      function: truthy