From d68fec242cb326a4ae1734982df95c7d62f49aab Mon Sep 17 00:00:00 2001 From: Martyn Davies Date: Thu, 22 Aug 2024 19:48:19 +0200 Subject: [PATCH] update readme formatting, links and utms (#275) --- README.md | 106 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 60 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index 07486bc..c0f831b 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,3 @@ -

- - - NPM Badge - License Badge - Discrod Badge -

-

@@ -14,6 +6,13 @@

+

+ + + NPM Badge + License Badge + Discrod Badge +

X (formerly Twitter) Follow @@ -44,46 +43,52 @@ At Zuplo we believe that the better the quality of an OpenAPI document, the better the developer experience will be for the consumers of that API. This experience is important for the success of an API. -Rate My OpenAPI is a suite of tools designed to help software developers using -OpenAPI to design and implement their APIs. Our tools include a website, a CLI, -a GitHub Action and an API, all aimed at ensuring your APIs meet high standards -of quality and usability. +_Rate My OpenAPI_ is a suite of tools designed to help software developers who +are using OpenAPI to design and implement their APIs. + +Our tools include a +[website](https://ratemyopenapi.com?utm_source=github&utm_medium=web), a +[CLI](https://www.npmjs.com/package/rmoa), a +[GitHub Action](https://github.com/marketplace/actions/rate-my-openapi-action) +and an [API](https://api.ratemyopenapi.com/docs/routes/introduction), all aimed +at ensuring your APIs meet high standards of quality and usability. ### Categories of Evaluation Our tools evaluate your OpenAPI definition files and provide a comprehensive score based on four key categories: -- Documentation: Ensure your API is well-documented, making it easy for +- **Documentation:** Ensure your API is well-documented, making it easy for users to understand and use. -- SDK Generation: Verify that your API definition supports SDK - generation, facilitating integration and usage in different programming - languages. -- Security: Check for best practices and standards to ensure your API is +- **SDK Generation:** Verify that your API definition supports SDK generation, + facilitating integration and usage in different programming languages. +- **Security:** Check for best practices and standards to ensure your API is secure and protected against common vulnerabilities. -- Completeness: Ensure your API definition is complete, with all - necessary endpoints, parameters, and responses accurately defined. +- **Completeness** Ensure your API definition is complete, with all necessary + endpoints, parameters, and responses accurately defined. ### Website -[https://ratemyopenapi.com](https://ratemyopenapi.com) offers a user-friendly -interface for developers to upload and analyze their OpenAPI definition files. +[https://ratemyopenapi.com](https://ratemyopenapi.com?utm_source=github&utm_medium=web) +offers a user-friendly interface for developers to upload and analyze their +OpenAPI definition files. Key features include: -- Linting: Upload & lint your OpenAPI files to receive detailed feedback. -- Comprehensive Scoring: Get a clear, actionable score rating your API's +- **Linting:** Upload & lint your OpenAPI files to receive detailed feedback. +- **Comprehensive Scoring:** Get a clear, actionable score rating your API's documentation, SDK generation, security, and completeness. -- Detailed Reports: Access in-depth reports that highlight areas of +- **Detailed Reports:** Access in-depth reports that highlight areas of improvement and provide recommendations. -- Visualization: Easily visualize the structure and quality of your API - with in-line feedback. +- **Visualization:** Easily visualize the structure and quality of your API with + in-line feedback. #### Getting Started -To get started visit [https://ratemyopenapi.com](https://ratemyopenapi.com), -upload your OpenAPI definition file & review the detailed reports to identify -areas for improvement +To get started visit +[https://ratemyopenapi.com](https://ratemyopenapi.com?utm_source=github&utm_medium=web), +upload your OpenAPI definition file and review the detailed reports to identify +areas for improvement. ### CLI @@ -92,9 +97,9 @@ or need to integrate quality checks into their development workflow. Key features include: -- Automated Checks: Integrate the CLI into your CI/CD pipeline for +- <**Automated Checks:** Integrate the CLI into your CI/CD pipeline for automated quality checks on every commit. -- Detailed Output: Get detailed feedback directly in your terminal, with +- **Detailed Output:** Get detailed feedback directly in your terminal, with options to further integrate these results into your development flow. #### Getting Started @@ -108,46 +113,55 @@ npm install rmoa rmoa lint --filename --api-key ``` -Source code & documentation at [packages/cli](/packages/cli/README.md). +CLI source code and documentation can be found at +[packages/cli](/packages/cli/README.md). To get an `API_KEY` sign up for free at [https://api.ratemyopenapi.com/docs](https://api.ratemyopenapi.com/docs). ### GitHub Action -Our GitHub action seamlessly integrates with your repository to ensure your APIs -are consistently of high quality. Key features include: +Our GitHub Action seamlessly integrates with your repository to ensure your APIs +are consistently of high quality. + +Key features include: -- Automated Linting: Automatically lint OpenAPI definition files on every +- **Automated Linting:** Automatically lint OpenAPI definition files on every pull request and push to ensure code quality. -- Inline Feedback: Receive feedback directly in your pull requests with +- **Inline Feedback:** Receive feedback directly in your pull requests with comments highlighting issues and areas for improvement. -- Continuous Improvement: Maintain a high standard of API quality with +- **Continuous Improvement:** Maintain a high standard of API quality with continuous monitoring and feedback. #### Getting Started -To get started add our GitHub action to your repository & configure it to run on -Pull Requests and Pushes to ensure continuous quality monitoring. +To get started add our GitHub action to your repository and configure it to run +on Pull Requests and Pushes to ensure continuous quality monitoring. -```bash +```yaml steps: - uses: actions/checkout@v4 - uses: zuplo/rmoa-action@v1 with: - filepath: './my-api.json' + filepath: "./my-api.json" apikey: ${{ secrets.RMOA_API_KEY }} ``` -Source code & documentation at -[rmoa-action](https://github.com/zuplo/rmoa-action) +GitHub Action source code and documentation can be found at +[rmoa-action](https://github.com/zuplo/rmoa-action). + +#### Getting an API key + +To get an `API_KEY` you can sign up for free at +[https://api.ratemyopenapi.com/docs](https://api.ratemyopenapi.com/docs). ### APIs -All our tools make use of our APIs to analyze and provide detailed results. You -can also make direct use of these APIs, which is a great option for those +All our tools make use of our APIs to analyze and provide detailed results. + +You can also make direct use of these APIs, which is a great option for those developers that want to build their own tools or integrate the Rate My OpenAPI -lint capabilities in a way that's not covered the existing tools. +linting capabilities in a way that's not covered the existing tools. #### Getting Started