diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS index c9f4455..61398c6 100644 --- a/.github/CODEOWNERS +++ b/.github/CODEOWNERS @@ -1,5 +1,9 @@ # These owners will be the default owners for everything in + # the repo. Unless a later match takes precedence, + # following users will be requested for + # review when someone opens a pull request. -* @fm-sick @vervoortb @haliCR1 @BaRu-ifm @julian-st @lorandmolnar @mrentsch65 @roeseko + +- @fm-sick @vervoortb @haliCR1 @BaRu-ifm @lorandmolnar @roesekoSICKAG @OlafWestrik @wolfram-ladurner @alexkrizsan @phkomma diff --git a/.github/workflows/linting.yml b/.github/workflows/linting.yml index beea1d4..2a0f130 100644 --- a/.github/workflows/linting.yml +++ b/.github/workflows/linting.yml @@ -1,4 +1,4 @@ -name: Lint RestAPI with Spectral +name: Run Spectral on Pull Requests on: - push @@ -10,10 +10,16 @@ jobs: runs-on: ubuntu-latest steps: # Check out the repository - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 # Run Spectral - - uses: stoplightio/spectral-action@latest + - uses: stoplightio/spectral-action@v0.8.12 with: - file_glob: 'JSON_for_IO-Link.yaml' - spectral_ruleset: spectral.yaml + file_glob: "JSON_for_IO-Link_unmerged.yaml" + spectral_ruleset: .spectral.yaml + + # Run Spectral + - uses: stoplightio/spectral-action@v0.8.12 + with: + file_glob: "MQTT_for_IO-Link_unmerged.yaml" + spectral_ruleset: .spectral.yaml diff --git a/.github/workflows/spec-merge.yml b/.github/workflows/spec-merge.yml new file mode 100644 index 0000000..834025d --- /dev/null +++ b/.github/workflows/spec-merge.yml @@ -0,0 +1,49 @@ +name: Merge async api specification + +on: + - push + - pull_request + +jobs: + build: + name: Run swagger-merger + runs-on: ubuntu-latest + steps: + # Check out the repository + - uses: actions/checkout@v4 + + # install swagger-merger + - name: install swagger-merger + run: npm install -g swagger-merger + + # Run swagger-merger + - name: Run swagger-merger + run: | + swagger-merger -i MQTT_for_IO-Link_unmerged.yaml schemas.yaml examples.yaml -o MQTT_for_IO-Link.yaml + swagger-merger -i JSON_for_IO-Link_unmerged.yaml schemas.yaml examples.yaml -o JSON_for_IO-Link.yaml + + - name: Upload merged MQTT_for_IO-Link YAML file as artifact + uses: actions/upload-artifact@v4 + with: + name: mqtt-yaml + path: MQTT_for_IO-Link.yaml + + - name: Upload merged JSON_for_IO-Link YAML file as artifact + uses: actions/upload-artifact@v4 + with: + name: json-yaml + path: JSON_for_IO-Link.yaml + + - name: Create release + uses: softprops/action-gh-release@v2 + if: github.ref_type == 'tag' + with: + files: | + JSON_for_IO-Link.yaml + MQTT_for_IO-Link.yaml + LICENSE + body_path: ${{ github.workspace }}/changelog.md + draft: true + prerelease: false + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.ruleset.yaml b/.ruleset.yaml new file mode 100644 index 0000000..0404356 --- /dev/null +++ b/.ruleset.yaml @@ -0,0 +1,847 @@ +description: Recommended rules for a high quality specification. +documentationUrl: https://quobix.com/vacuum/rulesets/recommended +rules: + component-description: + category: + description: Documentation is really important, in OpenAPI, just about everything can and should have a description. This set of rules checks for absent descriptions, poor quality descriptions (copy/paste), or short descriptions. + id: descriptions + name: Descriptions + description: Component description check + formats: + - oas3 + - oas3_1 + given: $ + howToFix: Components are the inputs and outputs of a specification. A user needs to be able to understand each component and what id does. Descriptions are critical to understanding components. Add a description! + id: component-description + recommended: true + resolved: true + severity: warn + then: + function: oasComponentDescriptions + type: validation + duplicated-entry-in-enum: + category: + description: Schemas are how request bodies and response payloads are defined. They define the data going in and the data flowing out of an operation. These rules check for structural validity, checking types, checking required fields and validating correct use of structures. + id: schemas + name: Schemas + description: Enum values must not have duplicate entry + formats: + - oas3 + - oas3_1 + - oas2 + given: $ + howToFix: Enums need to be unique, you can't duplicate them in the same definition. Please remove the duplicate value. + id: duplicated-entry-in-enum + recommended: true + severity: error + then: + function: duplicatedEnum + type: validation + info-description: + category: + description: The info object contains licencing, contact, authorship details and more. Checks to confirm required details have been completed. + id: information + name: Contract Information + description: Info section is missing a description + formats: + - oas3 + - oas3_1 + - oas2 + given: $ + howToFix: The 'info' section is missing a description, surely you want people to know what this spec is all about, right? + id: info-description + recommended: true + resolved: true + severity: error + then: + function: infoDescription + type: validation + info-license-spdx: + category: + description: The info object contains licencing, contact, authorship details and more. Checks to confirm required details have been completed. + id: information + name: Contract Information + description: License section cannot contain both an identifier and a URL, they are mutually exclusive. + formats: + - oas3 + - oas3_1 + - oas2 + given: $ + howToFix: A license can contain either a URL or an SPDX identifier, but not both, They are mutually exclusive and cannot both be present. Choose one or the other + id: info-license-spdx + recommended: true + resolved: true + severity: error + then: + function: infoLicenseURLSPDX + type: validation + no-$ref-siblings: + category: + description: Schemas are how request bodies and response payloads are defined. They define the data going in and the data flowing out of an operation. These rules check for structural validity, checking types, checking required fields and validating correct use of structures. + id: schemas + name: Schemas + description: $ref values cannot be placed next to other properties (like a description) + formats: + - oas2 + - oas3 + given: $ + howToFix: $ref values must not be placed next to sibling nodes, There should only be a single node when using $ref. A common mistake is adding 'description' next to a $ref. This is wrong. remove all siblings! + id: no-$ref-siblings + recommended: true + severity: error + then: + function: refSiblings + type: validation + no-ambiguous-paths: + category: + description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth. + id: operations + name: Operations + description: Paths need to resolve unambiguously from one another + formats: + - oas3 + - oas3_1 + - oas2 + given: $ + howToFix: Paths must all resolve unambiguously, they can't be confused with one another (/{id}/ambiguous and /ambiguous/{id} are the same thing. Make sure every path and the variables used are unique and do conflict with one another. Check the ordering of variables and the naming of path segments. + id: no-ambiguous-paths + recommended: true + resolved: true + severity: error + then: + function: noAmbiguousPaths + type: validation + no-eval-in-markdown: + category: + description: Validation rules make sure that certain characters or patterns have not been used that may cause issues when rendering in different types of applications. + id: validation + name: Validation + description: Markdown descriptions must not have `eval()` statements' + formats: + - oas3 + - oas3_1 + - oas2 + given: $ + howToFix: Remove all references to 'eval()' in the description. These can be used by malicious actors to embed code in contracts that is then executed when read by a browser. + id: no-eval-in-markdown + recommended: true + resolved: true + severity: error + then: + function: noEvalDescription + functionOptions: + pattern: eval\( + type: validation + no-http-verbs-in-path: + category: + description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth. + id: operations + name: Operations + description: Path segments must not contain an HTTP verb + formats: + - oas3 + - oas3_1 + - oas2 + given: $ + howToFix: When HTTP verbs (get/post/put etc) are used in path segments, it muddies the semantics of REST and creates a confusing and inconsistent experience. It's highly recommended that verbs are not used in path segments. Replace those HTTP verbs with more meaningful nouns. + id: no-http-verbs-in-path + recommended: true + severity: warn + then: + function: noVerbsInPath + type: style + no-request-body: + category: + description: Operations are the core of the contract, they define paths and HTTP methods. These rules check operations have been well constructed, looks for operationId, parameter, schema and return types in depth. + id: operations + name: Operations + description: HTTP GET and DELETE should not accept request bodies + formats: + - oas3 + - oas3_1 + given: $ + howToFix: Remove 'requestBody' from HTTP GET and DELETE methods + id: no-request-body + recommended: true + severity: warn + then: + function: noRequestBody + type: style + no-script-tags-in-markdown: + category: + description: Validation rules make sure that certain characters or patterns have not been used that may cause issues when rendering in different types of applications. + id: validation + name: Validation + description: Markdown descriptions must not have `