search

ipfs / pinning-services-api-spec

Standalone, vendor-agnostic Pinning Service API for IPFS ecosystem
https://ipfs.github.io/pinning-services-api-spec/
Creative Commons Zero v1.0 Universal
99 stars 26 forks source link

feat: add `operationId`s #95

Closed olizilla closed 2 years ago

olizilla commented 2 years ago

adds operationId properties to all routes. These can be used by code generators like openapi-backend to map routes to method names.

Unique string used to identify the operation. The id MUST be unique among all operations described in the API. The operationId value is case-sensitive. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. – https://swagger.io/specification/#operation-object

Handlers are registered for operationIds found in the OpenAPI definitions. – https://github.com/anttiviljami/openapi-backend#registering-handlers-for-operations

also fixes the linting warnings:

$ npx @stoplight/spectral-cli lint ./ipfs-pinning-service.yaml

/Users/oli/Code/ipfs/pinning-services-api-spec/ipfs-pinning-service.yaml
   2:6   warning  info-contact           Info object must have "contact" object.         info
  276:9  warning  operation-operationId  Operation must have "operationId".              paths./pins.get
 280:11  warning  operation-tag-defined  Operation tags must be defined in global tags.  paths./pins.get.tags[0]
 309:10  warning  operation-operationId  Operation must have "operationId".              paths./pins.post
 313:11  warning  operation-tag-defined  Operation tags must be defined in global tags.  paths./pins.post.tags[0]
  347:9  warning  operation-operationId  Operation must have "operationId".              paths./pins/{requestid}.get
 351:11  warning  operation-tag-defined  Operation tags must be defined in global tags.  paths./pins/{requestid}.get.tags[0]
 371:10  warning  operation-operationId  Operation must have "operationId".              paths./pins/{requestid}.post
 375:11  warning  operation-tag-defined  Operation tags must be defined in global tags.  paths./pins/{requestid}.post.tags[0]
 401:12  warning  operation-operationId  Operation must have "operationId".              paths./pins/{requestid}.delete
 405:11  warning  operation-tag-defined  Operation tags must be defined in global tags.  paths./pins/{requestid}.delete.tags[0]

✖ 11 problems (0 errors, 11 warnings, 0 infos, 0 hints)

License: (Apache-2.0 AND MIT) Signed-off-by: Oli Evans oli@tableflip.io

olizilla commented 2 years ago

As an aside: any reason not to do the linting via the npm module? If we add a default .spectral.json to the repo we can do

npx @stoplight/spectral-cli lint ./ipfs-pinning-service.yaml

The current lint set up does not surface warnings, and requires some digging to figure out.