Skip to content

Commit

Permalink
update readme formatting, links and utms (#275)
Browse files Browse the repository at this point in the history
  • Loading branch information
@martyndavies
martyndavies authored Aug 22, 2024
1 parent 0fcef37 commit d68fec2
Showing 1 changed file with 60 additions and 46 deletions.
106 changes: 60 additions & 46 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,3 @@
<p align="center">
<a aria-label="Zuplo logo" href="https://zuplo.com">
<img src="https://img.shields.io/badge/MADE%20BY%20Zuplo-FF00BD.svg?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHZpZXdCb3g9IjAgMCAzNyAzMiIgYXJpYS1oaWRkZW49InRydWUiPgogIDxwYXRoIGZpbGw9IiNGRjAwQkQiIGQ9Ik0yNy4xNDIgMTkuOTc4SDE2LjYyTDI3LjgzIDguNzQ2YS43NTguNzU4IDAgMDAtLjUzNC0xLjI5M0g5LjQ4OFYwaDE5LjUzNGE3LjU3MyA3LjU3MyAwIDAxNC4wNjUgMS4xMjUgNy41OTEgNy41OTEgMCAwMTIuODM2IDMuMTI2IDcuNDAyIDcuNDAyIDAgMDEtMS40NjEgOC4zOThsLTcuMzIgNy4zMjh6Ii8+CiAgPHBhdGggZmlsbD0iI0ZGMDBCRCIgZD0iTTkuNDg5IDExLjA0MmgxMC41MjRsLTExLjE5IDExLjIxYS43NzIuNzcyIDAgMDAuNTQzIDEuMzE2aDE3Ljc1OXY3LjQ1Mkg3LjYxYTcuNTc0IDcuNTc0IDAgMDEtNC4wNjUtMS4xMjVBNy41OTMgNy41OTMgMCAwMS43MSAyNi43NjhhNy40MDMgNy40MDMgMCAwMTEuNDYyLTguMzk3bDcuMzE4LTcuMzI5eiIvPgo8L3N2Zz4K&labelColor=000"></a>
<a aria-label="NPM version" href="https://www.npmjs.com/package/rmoa"><img alt="NPM Badge" src="https://img.shields.io/npm/v/rmoa.svg?style=for-the-badge&labelColor=000000"></a>
<a aria-label="License" href="https://github.com/zuplo/rate-my-openapi/blob/main/LICENSE"><img alt="License Badge" src="https://img.shields.io/npm/l/rmoa.svg?style=for-the-badge&labelColor=000000"></a>
<a aria-label="Join the community on Discord" href="https://discord.com/channels/848913990360629268/1235294876778627246"><img alt="Discrod Badge" src="https://img.shields.io/badge/Chat%20on%20discord-5865F2.svg?style=for-the-badge&logo=discord&labelColor=000000&logoWidth=20"></a>
</p>

<p align="center">
<a href="https://ratemyopenapi.com/">
<img src="https://cdn.zuplo.com/static/logos/logo.svg" height="50">
Expand All @@ -14,6 +6,13 @@
</p>

<div align="center">
<p align="center">
<a aria-label="Zuplo logo" href="https://zuplo.com">
<img src="https://img.shields.io/badge/MADE%20BY%20Zuplo-FF00BD.svg?style=for-the-badge&logo=data:image/svg%2bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIGZpbGw9Im5vbmUiIHZpZXdCb3g9IjAgMCAzNyAzMiIgYXJpYS1oaWRkZW49InRydWUiPgogIDxwYXRoIGZpbGw9IiNGRjAwQkQiIGQ9Ik0yNy4xNDIgMTkuOTc4SDE2LjYyTDI3LjgzIDguNzQ2YS43NTguNzU4IDAgMDAtLjUzNC0xLjI5M0g5LjQ4OFYwaDE5LjUzNGE3LjU3MyA3LjU3MyAwIDAxNC4wNjUgMS4xMjUgNy41OTEgNy41OTEgMCAwMTIuODM2IDMuMTI2IDcuNDAyIDcuNDAyIDAgMDEtMS40NjEgOC4zOThsLTcuMzIgNy4zMjh6Ii8+CiAgPHBhdGggZmlsbD0iI0ZGMDBCRCIgZD0iTTkuNDg5IDExLjA0MmgxMC41MjRsLTExLjE5IDExLjIxYS43NzIuNzcyIDAgMDAuNTQzIDEuMzE2aDE3Ljc1OXY3LjQ1Mkg3LjYxYTcuNTc0IDcuNTc0IDAgMDEtNC4wNjUtMS4xMjVBNy41OTMgNy41OTMgMCAwMS43MSAyNi43NjhhNy40MDMgNy40MDMgMCAwMTEuNDYyLTguMzk3bDcuMzE4LTcuMzI5eiIvPgo8L3N2Zz4K&labelColor=000"></a>
<a aria-label="NPM version" href="https://www.npmjs.com/package/rmoa"><img alt="NPM Badge" src="https://img.shields.io/npm/v/rmoa.svg?style=for-the-badge&labelColor=000000"></a>
<a aria-label="License" href="https://github.com/zuplo/rate-my-openapi/blob/main/LICENSE"><img alt="License Badge" src="https://img.shields.io/npm/l/rmoa.svg?style=for-the-badge&labelColor=000000"></a>
<a aria-label="Join the community on Discord" href="https://discord.com/channels/848913990360629268/1235294876778627246"><img alt="Discrod Badge" src="https://img.shields.io/badge/Chat%20on%20discord-5865F2.svg?style=for-the-badge&logo=discord&labelColor=000000&logoWidth=20"></a>
</p>
<a href="https://twitter.com/zuplo">
<img alt="X (formerly Twitter) Follow" src="https://img.shields.io/twitter/follow/zuplo">
</a>
Expand Down Expand Up @@ -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:

- <b>Documentation:</b> 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.
- <b>SDK Generation:</b> Verify that your API definition supports SDK
generation, facilitating integration and usage in different programming
languages.
- <b>Security:</b> 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.
- <b>Completeness:</b> 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:

- <b>Linting:</b> Upload & lint your OpenAPI files to receive detailed feedback.
- <b>Comprehensive Scoring:</b> 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.
- <b>Detailed Reports:</b> Access in-depth reports that highlight areas of
- **Detailed Reports:** Access in-depth reports that highlight areas of
improvement and provide recommendations.
- <b>Visualization:</b> 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

Expand All @@ -92,9 +97,9 @@ or need to integrate quality checks into their development workflow.

Key features include:

- <b>Automated Checks:</b> 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.
- <b>Detailed Output:</b> 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
Expand All @@ -108,46 +113,55 @@ npm install rmoa
rmoa lint --filename <openapi-filename> --api-key <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:

- <b>Automated Linting:</b> Automatically lint OpenAPI definition files on every
- **Automated Linting:** Automatically lint OpenAPI definition files on every
pull request and push to ensure code quality.
- <b>Inline Feedback:</b> 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.
- <b>Continuous Improvement:</b> 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

Expand Down

0 comments on commit d68fec2

Please sign in to comment.