Skip to content

Commit

Permalink
docs: fix grammatic on initial readme
Browse files Browse the repository at this point in the history
  • Loading branch information
a-chacon committed Jul 21, 2024
1 parent 7a08bca commit f851ea3
Showing 1 changed file with 12 additions and 12 deletions.
24 changes: 12 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,24 +1,20 @@
# Open API Specification On Rails

OasRails is a Rails engine for generate **automatic interactive documentation in your rails APIs**. Basically it generate an **OAS 3.1** document and then display it on **[SwaggerUI](https://github.com/swagger-api/swagger-ui)**.
OasRails is a Rails engine for generating **automatic interactive documentation for your Rails APIs**. Basically, it generates an **OAS 3.1** document and displays it using **[SwaggerUI](https://github.com/swagger-api/swagger-ui)**.

**Related Projects**:

- [ApiPie](https://github.com/Apipie/apipie-rails) (Don't support OAS 3.1, You need to learn a DSL, Not nice UI)
- [swagger_yard-rails](https://github.com/livingsocial/swagger_yard-rails) (Seems to be abandoned, but this works like inspiration)
- [Rswag](https://github.com/rswag/rswag) (Not automatic, depend on Rspec and default test suit now is Minitest)
- [ApiPie](https://github.com/Apipie/apipie-rails) (Doesn't support OAS 3.1, requires learning a DSL, lacks a nice UI)
- [swagger_yard-rails](https://github.com/livingsocial/swagger_yard-rails) (Seems abandoned, but serves as inspiration)
- [Rswag](https://github.com/rswag/rswag) (Not automatic, depends on RSpec; default test suite now is Minitest)

### Motivation

So, after giving a try to fast-api framework in python I was deeply facinating with his interactive documentation and came back to Ruby on Rails seeking the same but I cant find it. I write a [stackoverflow](https://stackoverflow.com/questions/71947018/is-there-a-way-to-generate-an-interactive-documentation-for-rails-apis) question years ago and found nothing. So now that I have time and was working as a freelancer developing an API I decided to try to build my own tool for do it and here we are.
After trying the fast-api framework in Python, I was deeply fascinated by its interactive documentation. When I returned to Ruby on Rails, I sought similar functionality but couldn't find it. Years ago, I posted a [question on Stack Overflow](https://stackoverflow.com/questions/71947018/is-there-a-way-to-generate-an-interactive-documentation-for-rails-apis) and found nothing. Now, with some free time while freelancing as an API developer, I decided to try building my own tool for it, and here we are.

**This is not a production ready solution**. I am working on it, but you can give a try and if you like the idea please think in contributing to build it.
**This is not yet a production-ready solution**. I am actively working on it, but you can try it out. If you like the idea, please consider contributing to its development.

The idea is to have do the less for have a complete documentation and if you follow the REST principles in Rails I think we can do it. Then you can complement the documentation with [Yard](https://yardoc.org/) tags.

## Usage

How to use my plugin.
The goal is to do the least amount of work to get a complete documentation. If you follow REST principles in Rails, I believe we can achieve that. You can complement the documentation with [Yard](https://yardoc.org/) tags.

## Installation

Expand All @@ -40,7 +36,11 @@ And finally mount the engine in your `route.rb` file:
mount OasRails::Engine => '/docs'
```

You will have a very **basic documentation** based on your routes and the information that the engine can get automatically on `localhost:3000/docs`. Then **we should complement it** with an initializer file and [Yard](https://yardoc.org/) tags on ower controllers methods.
You will have very **basic documentation** based on your routes and the information that the engine can get automatically at `localhost:3000/docs`. Then, **we should complement it** with an initializer file and [Yard](https://yardoc.org/) tags on our controller methods.

## Usage

To be completed soon...

## Contributing

Expand Down

0 comments on commit f851ea3

Please sign in to comment.