rest ruler
v2.1.1
Die Rücksteller -CLI ist ein Tool, das erholsame APIs anhand von Verstößen gegen die Entwurfsregel bewerten kann. Diese Verstöße basieren auf den Entwurfsregeln aus Mark Massés Buch REST API -Designregelbuch. Derzeit kann der Rückschritt die folgenden Sprachen der Web -API -Beschreibung analysieren:
Der Restuler wurde in der empirischen Software -Engineering -Gruppe der Universität von Stuttgart als Forschungsprototyp in Java (Version> = 18 benötigt) entwickelt. Es ist ein Befehlszeilen-Tool, das den Pfad oder die URL als Eingabe in eine OpenAPI-Definitionsdatei bringt und eine Liste von Verstößen gegen die Entwurfsregel als Ausgabe anzeigt. Optional kann eine Markdown -Berichtsdatei mit zusätzlichen Details und Verbesserungsvorschlägen generiert werden.
Beschreibungen der implementierten Designregeln finden Sie in unserer Regeldokumentation.
Eine detaillierte Beschreibung des Projekts und implementierten Komponenten finden Sie in der Architekturdokumentation.
Sie finden die Artefakte, die sich auf die empirische Bewertung des Rückstellers in diesem Repository beziehen.
Für einen kurzen Start können Sie einfach rest-ruler.jar für eine bestimmte Veröffentlichung herunterladen. Führen Sie diese Befehle dann in demselben Ordner wie die JAR -Datei aus (Java -Version> = 18 benötigt):
# execute JAR file to display CLI parameters
java -jar rest-ruler.jar -h
# run with an example API from https://apis.guru
java -jar rest-ruler.jar -p https://api.apis.guru/v2/specs/circleci.com/v1/openapi.yamlWenn Sie das vollständige Repository herunterladen oder klonen möchten, führen Sie diese Befehle im Stammordner des Repositorys aus, um das Tool zu erstellen und zu starten (Java -Version> = 18 benötigt):
# create JAR file
./gradlew assemble
# execute JAR file to display CLI parameters
java -jar build/libs/rest-ruler.jar -h
# run tests
./gradlew test
# test coverage (output: ./build/reports/jacoco/test/html/index.html)
./gradlew jacocoTestReport # run with an example API from https://apis.guru
java -jar build/libs/rest-ruler.jar -p https://api.apis.guru/v2/specs/circleci.com/v1/openapi.yamlDies erzeugt die folgende Ausgabe:
java -jar build/libs/rest-ruler.jar -p https://api.apis.guru/v2/specs/circleci.com/v1/openapi.yaml
----------------START ANALYSIS----------------
-----------------------------------------------
Begin with the analysis of the file from: https://api.apis.guru/v2/specs/circleci.com/v1/openapi.yaml
----------------------------------------------
Aug 11, 2023 3:45:01 PM cli.analyzer.RestAnalyzer runRuleViolationChecks
INFO: Rule 1 of 15 is now checked:
CRUD function names should not be used in URIs
[==========] 100%
Aug 11, 2023 3:45:01 PM cli.analyzer.RestAnalyzer runRuleViolationChecks
INFO: Rule 2 of 15 is now checked:
GET must be used to retrieve a representation of a resource
[==========] 100%
Aug 11, 2023 3:45:01 PM cli.analyzer.RestAnalyzer runRuleViolationChecks
INFO: Rule 3 of 15 is now checked:
Forward slash separator (/) must be used to indicate a hierarchical relationship
[==========] 100%
Aug 11, 2023 3:45:01 PM cli.analyzer.RestAnalyzer runRuleViolationChecks
INFO: Rule 4 of 15 is now checked:
A verb or verb phrase should be used for controller names
[==========] 100%
Aug 11, 2023 3:45:03 PM cli.analyzer.RestAnalyzer runRuleViolationChecks
INFO: Rule 5 of 15 is now checked:
Hyphens (-) should be used to improve the readability of URIs
[==========] 100%
Aug 11, 2023 3:45:04 PM cli.analyzer.RestAnalyzer runRuleViolationChecks
INFO: Rule 6 of 15 is now checked:
File extensions should not be included in URIs
[==========] 100%
Aug 11, 2023 3:45:04 PM cli.analyzer.RestAnalyzer runRuleViolationChecks
INFO: Rule 7 of 15 is now checked:
GET and POST must not be used to tunnel other request methods
[==========] 100%
Aug 11, 2023 3:45:04 PM cli.analyzer.RestAnalyzer runRuleViolationChecks
INFO: Rule 8 of 15 is now checked:
A singular noun should be used for document names
[==========] 100%
Aug 11, 2023 3:45:08 PM cli.analyzer.RestAnalyzer runRuleViolationChecks
INFO: Rule 9 of 15 is now checked:
Description of request should match with the type of the request.
Aug 11, 2023 3:45:08 PM cli.analyzer.RestAnalyzer runRuleViolationChecks
INFO: Rule 10 of 15 is now checked:
401 ("Unauthorized") must be used when there is a problem with the client's credentials
[==========] 100%
Aug 11, 2023 3:45:08 PM cli.analyzer.RestAnalyzer runRuleViolationChecks
INFO: Rule 11 of 15 is now checked:
Underscores (_) should not be used in URI
[==========] 100%
Aug 11, 2023 3:45:08 PM cli.analyzer.RestAnalyzer runRuleViolationChecks
INFO: Rule 12 of 15 is now checked:
Content-Type must be used
[==========] 100%
Aug 11, 2023 3:45:08 PM cli.analyzer.RestAnalyzer runRuleViolationChecks
INFO: Rule 13 of 15 is now checked:
Lowercase letters should be preferred in URI paths
[==========] 100%
Aug 11, 2023 3:45:08 PM cli.analyzer.RestAnalyzer runRuleViolationChecks
INFO: Rule 14 of 15 is now checked:
A trailing forward slash (/) should not be included in URIs
[==========] 100%
Aug 11, 2023 3:45:08 PM cli.analyzer.RestAnalyzer runRuleViolationChecks
INFO: Rule 15 of 15 is now checked:
A plural noun should be used for collection or store names
[==========] 100%
REST API Specification Report
=============================
| Line No. | Line | Rule Violated |
| -------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| 27 | /me | 401 ("Unauthorized") must be used when there is a problem with the client's credentials |
| 38 | /project/{username}/{project} | 401 ("Unauthorized") must be used when there is a problem with the client's credentials |
| 38 | /project/{username}/{project} | 401 ("Unauthorized") must be used when there is a problem with the client's credentials |
| 38 | /project/{username}/{project} | A plural noun should be used for collection or store names |
| 80 | /project/{username}/{project}/build-cache | 401 ("Unauthorized") must be used when there is a problem with the client's credentials |
| 80 | /project/{username}/{project}/build-cache | A plural noun should be used for collection or store names |
| 80 | /project/{username}/{project}/build-cache | A verb or verb phrase should be used for controller names |
| 97 | /project/{username}/{project}/checkout-key | 401 ("Unauthorized") must be used when there is a problem with the client's credentials |
| 97 | /project/{username}/{project}/checkout-key | 401 ("Unauthorized") must be used when there is a problem with the client's credentials |
| 97 | /project/{username}/{project}/checkout-key | A plural noun should be used for collection or store names |
| 128 | /project/{username}/{project}/checkout-key/{fingerprint} | 401 ("Unauthorized") must be used when there is a problem with the client's credentials |
| 128 | /project/{username}/{project}/checkout-key/{fingerprint} | 401 ("Unauthorized") must be used when there is a problem with the client's credentials |
| 128 | /project/{username}/{project}/checkout-key/{fingerprint} | A plural noun should be used for collection or store names |
| 154 | /project/{username}/{project}/envvar | 401 ("Unauthorized") must be used when there is a problem with the client's credentials |
| 154 | /project/{username}/{project}/envvar | 401 ("Unauthorized") must be used when there is a problem with the client's credentials |
| 154 | /project/{username}/{project}/envvar | A plural noun should be used for collection or store names |
| 154 | /project/{username}/{project}/envvar | Hyphens (-) should be used to improve the readability of URIs |
| 170 | /project/{username}/{project}/envvar/{name} | 401 ("Unauthorized") must be used when there is a problem with the client's credentials |
| 170 | /project/{username}/{project}/envvar/{name} | 401 ("Unauthorized") must be used when there is a problem with the client's credentials |
| 170 | /project/{username}/{project}/envvar/{name} | A plural noun should be used for collection or store names |
| 197 | /project/{username}/{project}/ssh-key | 401 ("Unauthorized") must be used when there is a problem with the client's credentials |
| 197 | /project/{username}/{project}/ssh-key | A plural noun should be used for collection or store names |
| 237 | /project/{username}/{project}/tree/{branch} | 401 ("Unauthorized") must be used when there is a problem with the client's credentials |
| 237 | /project/{username}/{project}/tree/{branch} | A plural noun should be used for collection or store names |
| 272 | /project/{username}/{project}/{build_num} | 401 ("Unauthorized") must be used when there is a problem with the client's credentials |
| 272 | /project/{username}/{project}/{build_num} | A plural noun should be used for collection or store names |
| 288 | /project/{username}/{project}/{build_num}/artifacts | 401 ("Unauthorized") must be used when there is a problem with the client's credentials |
| 288 | /project/{username}/{project}/{build_num}/artifacts | A plural noun should be used for collection or store names |
| 303 | /project/{username}/{project}/{build_num}/cancel | 401 ("Unauthorized") must be used when there is a problem with the client's credentials |
| 303 | /project/{username}/{project}/{build_num}/cancel | A plural noun should be used for collection or store names |
| 303 | /project/{username}/{project}/{build_num}/cancel | Description of request should match with the type of the request. |
| 318 | /project/{username}/{project}/{build_num}/retry | 401 ("Unauthorized") must be used when there is a problem with the client's credentials |
| 318 | /project/{username}/{project}/{build_num}/retry | A plural noun should be used for collection or store names |
| 333 | /project/{username}/{project}/{build_num}/tests | 401 ("Unauthorized") must be used when there is a problem with the client's credentials |
| 333 | /project/{username}/{project}/{build_num}/tests | A plural noun should be used for collection or store names |
| 333 | /project/{username}/{project}/{build_num}/tests | Description of request should match with the type of the request. |
| 350 | /projects | 401 ("Unauthorized") must be used when there is a problem with the client's credentials |
| 362 | /recent-builds | 401 ("Unauthorized") must be used when there is a problem with the client's credentials |
| 376 | /user/heroku-key | 401 ("Unauthorized") must be used when there is a problem with the client's credentials |
| 376 | /user/heroku-key | Hyphens (-) should be used to improve the readability of URIs |
----------------------------------------------
In total 40 rule violations were found
| Option | Beschreibung | Erforderlich |
|---|---|---|
-p $URI_PATH ,--path $URI_PATH | Lokale Pfad oder öffentliche URL zur OpenAPI -Definition (2.0 oder höher; JSON oder YAML) | JA |
-e ,--expertMode | Wählen Sie interaktiv die Regeln für die Analyse aus | NEIN |
-r ,--report | Generieren Sie eine Markdown -Berichtsdatei mit den Analyseergebnissen | NEIN* |
-rn $FILENAME ,--reportName $FILENAME | Geben Sie einen benutzerdefinierten Dateinamen für den Markdown -Bericht an. Wenn diese Option ausgewählt ist, ist die obige Option für die Ausgabe nicht erforderlich. | NEIN* |
*Wenn keine zusätzliche Ausgabe angegeben wurde, werden die Ergebnisse nur zur Konsole gedruckt.
# Run with local file and no output file
java -jar build/libs/rest-ruler.jar -p path/to/openapi/definiton.json
# Run with public URL and no output file
java -jar build/libs/rest-ruler.jar -p https://www.custom.domain.com/path/to/openapi-definiton.yaml
# Run with custom filename for Markdown report
java -jar build/libs/rest-ruler.jar -p path/to/openapi/definiton.yaml -rn custom-file-name
# Run with generated filename for Markdown report
java -jar build/libs/rest-ruler.jar -p path/to/openapi/definiton.yaml -r
# Run in expert mode
java -jar build/libs/rest-ruler.jar -p path/to/openapi/definiton.json -e
