rest ruler
v2.1.1
제한자 CLI는 설계 규칙 위반에 기초하여 RESTFUL API를 평가할 수있는 도구입니다. 이러한 위반은 Mark Massé의 Book REST API Design Rulebook의 디자인 규칙을 기반으로합니다. 현재 제한자는 다음 웹 API 설명 언어를 구문 분석 할 수 있습니다.
구속기는 독일 슈투트가르트 대학교 (University of Stuttgart)의 경험적 소프트웨어 엔지니어링 그룹에서 Java (버전> = 18 필요)로 작성된 연구 프로토 타입으로 개발되었습니다. 경로 또는 URL을 OpenAPI 정의 파일로 가져 와서 디자인 규칙 위반 목록을 출력으로 표시하는 명령 줄 도구입니다. 선택적으로 마크 다운 보고서 파일은 추가 세부 사항과 개선 제안으로 생성 될 수 있습니다.
구현 된 설계 규칙에 대한 설명은 규칙 문서에서 찾을 수 있습니다.
프로젝트 및 구현 된 구성 요소에 대한 자세한 설명은 아키텍처 문서에서 찾을 수 있습니다.
이 저장소에서 구속기의 경험적 평가와 관련된 아티팩트를 찾을 수 있습니다.
빠른 시작을 위해 특정 릴리스를 위해 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
