rest ruler
v2.1.1
限制性CLI是一種可以根據違規設計規則進行評估的工具。這些違規是基於馬克·馬斯（Marksé）的書籍REST API設計規則手冊的設計規則。當前，限制器可以解析以下Web API描述語言：
Drimpuler是在德國斯圖加特大學的經驗軟件工程小組中開發的，是用Java編寫的研究原型（需要版本> = 18）。它是一種命令行工具，將路徑或URL作為輸入作為輸入，並顯示違反設計規則的列表作為輸出。可選地，可以生成降級報告文件，並提供其他詳細信息和改進建議。
可以在我們的規則文檔中找到實施的設計規則的描述。
可以在體系結構文檔中找到對項目和已實施組件的詳細描述。
您會發現與此存儲庫中限制器的經驗評估有關的工件。
為了快速啟動，您只需下載rest-ruler.jar即可以獲取某個版本。然後在與JAR文件同一文件夾中執行這些命令（Java版本> = 18需要）：
# 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.yaml如果要下載或克隆完整的存儲庫，請在存儲庫的根文件夾中運行這些命令以構建和啟動工具（Java版本> = 18需要）：
# 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.yaml這會產生以下輸出：
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
| 選項 | 描述 | 必需的 |
|---|---|---|
-p $URI_PATH ，--path $URI_PATH | OpenAPI定義的本地路徑或公共URL（2.0或更高； JSON或YAML） | 是的 |
-e ，--expertMode | 互動選擇分析規則 | 不 |
-r ，--report | 生成帶有分析結果的Markdown報告文件 | 不* |
-rn $FILENAME ，--reportName $FILENAME | 為Markdown報告指定自定義文件名。如果選擇此選項，則不需要上述輸出選項。 | 不* |
*如果未指定額外的輸出，則結果將僅印刷到控制台。
# 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
