rest ruler
v2.1.1
La CLI du réperculaire est un outil qui peut évaluer les API reposantes sur la base des violations des règles de conception. Ces violations sont basées sur les règles de conception du livre de règles de conception API du livre de Mark Massé. Actuellement, le réperculaire peut analyser les langues de description de l'API Web suivantes:
Le réperculaire a été développé dans le groupe d'ingénierie logicielle empirique de l'Université de Stuttgart, en Allemagne, en tant que prototype de recherche écrit en Java (version> = 18 nécessaire). Il s'agit d'un outil de ligne de commande qui emmène le chemin ou l'URL dans un fichier de définition OpenAPI en entrée et affiche une liste des violations de règles de conception en sortie. Facultativement, un fichier de rapport Markdown peut être généré avec des détails supplémentaires et des suggestions d'amélioration.
Des descriptions des règles de conception implémentées se trouvent dans notre documentation de règles.
Une description détaillée du projet et des composants implémentées peut être trouvée dans la documentation de l'architecture.
Vous trouverez les artefacts liés à l'évaluation empirique du réperculaire dans ce référentiel.
Pour un démarrage rapide, vous pouvez simplement télécharger rest-ruler.jar pour une certaine version. Exécutez ensuite ces commandes dans le même dossier que le fichier jar (version java> = 18 nécessaire):
# 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.yamlSi vous souhaitez télécharger ou cloner le référentiel complet, exécutez ces commandes dans le dossier racine du référentiel pour créer et démarrer l'outil (version java> = 18 nécessaire):
# 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.yamlCela produit la sortie suivante:
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 | Description | Requis |
|---|---|---|
-p $URI_PATH ,--path $URI_PATH | Chemin local ou URL public vers OpenAPI Définition (2.0 ou plus; JSON ou YAML) | OUI |
-e ,--expertMode | Sélectionnez de manière interactive les règles de l'analyse | NON |
-r ,--report | Générez un fichier de rapport Markdown avec les résultats de l'analyse | NON* |
-rn $FILENAME ,--reportName $FILENAME | Spécifiez un nom de fichier personnalisé pour le rapport Markdown. Si cette option est sélectionnée, l'option ci-dessus pour la sortie n'est pas nécessaire. | NON* |
* Si aucune sortie supplémentaire n'a été spécifiée, les résultats ne seront imprimés que sur la console.
# 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
