documentation-zero 0.0.1 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b9268dac205c84212366821a80fbfc1b415c194acd5013bfd4263b95abb3b46d
-  data.tar.gz: b14a79c073247962b148fa46a61220fbb0669b49d12c8df24b38e5ca17975782
+  metadata.gz: 2650852c4529a8d663213c01b7c0b492fd81c601247c817ce17cf204a5f44872
+  data.tar.gz: b2eee6d289c54bf1ef547b0e8cf4f52df36bfd6b164ca96523b095daa37e35c4
 SHA512:
-  metadata.gz: fc628c160b2404f99ffa77d0d491d55e43ed902ba45379355b672783578fd89c98290aaa71dc12d725169bcccd93927cc302e9167fadb4b574a1e4f07dfde73d
-  data.tar.gz: 0d555dc8941e2599c25fee949790aadfadea4bd1610c5d152e29ecd28bd3a6dbd1e65ea2f82fbecbe793aadf9100a2546574827cc71f2b11d3a7b73ce12f17d7
+  metadata.gz: b8d1ef81d109b58cab60dd37b06eb9ba310a7fcfc8c59efcd7de8bc14fb907e90820dfeb6aefb62c4dea09326b367ec9f41d70dfab991b69e56608e2e3eb695d
+  data.tar.gz: a8de4dc6df6b59904c9b649fd27f9d443e98e6765234d1348fc55295718522ec638370f8f3b1dc34ffc41111747f99bb615a888d4031a43b6962ea74d013b356

data/.documentation_api/README.md

@@ -0,0 +1,79 @@
+# The Rails tabler API
+
+Welcome to the Rails tabler API! If you're looking to integrate your application with Rails tabler or create your own application in concert with data inside of Rails tabler, you're in the right place. We're happy to have you!
+
+## Making a request
+
+All URLs start with **`https://example.com/api/`**. URLs are HTTPS only. The path is prefixed with the `/api` prefix.
+
+To make a request for all the resources on your account, append the `resources` index path to the base URL to form something like `https://example.com/api/resources.json`. In cURL, it looks like this:
+
+``` shell
+curl -H "Authorization: Bearer $ACCESS_TOKEN" -H 'User-Agent: MyApp (yourname@example.com)' https://example.com/api/resources.json
+```
+
+## Identifying your application
+
+You must include a `User-Agent` header with **both**:
+
+* The name of your application
+* A link to your application or your email address
+
+We use this information to get in touch if you're doing something wrong (so we can warn you before you're blacklisted) or something awesome (so we can congratulate you). Here are examples of acceptable `User-Agent` headers:
+
+* `User-Agent: Freshbooks (http://freshbooks.com/contact.php)`
+* `User-Agent: Fabian's Ingenious Integration (fabian@example.com)`
+
+If you don't include a `User-Agent` header, you'll get a `400 Bad Request` response.
+
+## JSON only
+
+We use JSON for all API data. The style is no root element and snake\_case for object keys. This means that you have to send the `Content-Type` header `Content-Type: application/json; charset=utf-8` when you're POSTing or PUTing data into Rails tabler. All API URLs end in `.json` to indicate that they return JSON. Alternatively you can send `Accept: application/json`.
+
+You'll receive a `415 Unsupported Media Type` response code if you don't include the `Content-Type` header.
+
+## Pagination
+
+Most collection APIs paginate their results. The number of requests that'll appear on each page is variable. In most cases, we use a [geared pagination ratio](https://github.com/basecamp/geared_pagination) with 15 results on page 1, 30 on page 2, 50 on 3, and then 100 on 4 and above. The Rails tabler API follows the [RFC5988 convention](https://tools.ietf.org/html/rfc5988) of using the `Link` header to provide URLs for the `next` page. Follow this convention to retrieve the next page of data—please don't build the pagination URLs yourself!
+
+Here's an example response header from requesting the third page of some resource:
+
+```
+Link: <https://example.com/api/resources.json?page=4>; rel="next"
+```
+
+If the `Link` header is blank, that's the last page. The Rails tabler API also provides the `X-Total-Count` header, which displays the total number of resources in the collection you are fetching.
+
+## Using HTTP caching
+
+You must use HTTP freshness headers to speed up your application and lighten the load on our servers. Most API responses will include an `ETag` or `Last-Modified` header. When you first request a resource, store these values. On subsequent requests, submit them back to us as `If-None-Match` and `If-Modified-Since`, respectively. If the resource hasn't changed since your last request, you'll get a `304 Not Modified` response with no body, saving you the time and bandwidth of sending something you already have.
+
+## Handling errors
+
+API clients must expect and gracefully handle transient errors, such as rate limiting or server errors. We recommend baking 5xx and 429 response handling into your low-level HTTP client so your integration can handle most errors automatically.
+
+### Rate limiting (429 Too Many Requests)
+
+You can perform up to 50 requests per 10-second period from the same IP address. If you exceed this limit, you'll get a [429 Too Many Requests](http://tools.ietf.org/html/draft-nottingham-http-new-status-02#section-4) response for subsequent requests. Check the `Retry-After` header to see how many seconds to wait before retrying the request.
+
+### [5xx server errors](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes#5xx_Server_errors)
+
+If Rails tabler is having trouble, you will get a response with a 5xx status code indicating a server error. 500 (Internal Server Error), 502 (Bad Gateway), 503 (Service Unavailable), and 504 (Gateway Timeout) may be retried with [exponential backoff](https://en.wikipedia.org/wiki/Exponential_backoff).
+
+### 404 Not Found
+
+API requests may 404 due to deleted content, an inactive account, missing user permissions, etc. Detect these conditions to give your users a clear explanation about why they can't connect to Rails tabler. Do not automatically retry these requests.
+
+## API endpoints
+
+<!-- START API ENDPOINTS -->
+
+- [Posts](sections/posts.md)
+
+<!-- END API ENDPOINTS -->
+
+---
+
+If you have a specific feature request or find a bug, please open a GitHub issue. We encourage you to fork these docs for local reference and happily accept pull requests with improvements.
+
+To talk with us and other developers about the API, [post a question on StackOverflow](http://stackoverflow.com/questions/ask) tagged `rails-tabler`. If you need help from us directly, please open a support ticket.

data/.documentation_api/sections/posts.md

@@ -0,0 +1,77 @@
+# Posts
+
+Endpoints:
+
+- [Get posts](#get-posts)
+- [Get post](#get-post)
+- [Create post](#create-post)
+- [Update post](#update-post)
+- [Delete post](#delete-post)
+
+## Get posts
+
+- `GET /posts.json` will return a [paginated list](../README.md#pagination) of posts.
+
+<!--
+_Optional query parameters_:
+
+* `attribute1` - when set to true, will only return resources that are completed.
+* `attribute2` - when set to true, will only return resources that are completed.
+-->
+
+See the [post](#model) model for more info on the response payload.
+
+## Get post
+
+- `GET /posts/1.json` will return the post with an ID of `1`.
+
+See the [post](#model) model for more info on the response payload.
+
+## Create post
+
+- `POST /posts.json` creates post.
+
+<!--
+**Required parameters**: `attribute1` and `attribute2`.
+-->
+
+_Optional parameters_:
+
+* `title` - attribute from post.
+* `content` - attribute from post.
+* `published` - attribute from post.
+
+This endpoint will return `201 Created` with the current JSON representation of the post if the creation was a success. See the [post](#model) model for more info on the payload.
+
+## Update post
+
+- `PUT /posts/1.json` allows changing the post with an ID of `1`.
+
+This endpoint will return `200 OK` with the current JSON representation of the post if the update was a success. See the [post](#model) model for more info on the payload.
+
+<!--
+**Required parameters**: `attribute1` and `attribute2`.
+-->
+
+_Optional parameters_:
+
+* `title` - attribute from post.
+* `content` - attribute from post.
+* `published` - attribute from post.
+
+## Delete post
+
+- `DELETE /posts/1.json` will delete the post with an ID of `1`.
+
+This endpoint will return `204 No Content` if successful. No parameters are required.
+
+---
+
+## Model
+```json
+{
+  "title": "string",
+  "content": "string",
+  "published": "boolean",
+}
+```

data/Gemfile.lock

@@ -0,0 +1,19 @@
+PATH
+  remote: .
+  specs:
+    documentation-zero (0.0.4)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    rake (13.0.6)
+
+PLATFORMS
+  x86_64-darwin-21
+
+DEPENDENCIES
+  documentation-zero!
+  rake (~> 13.0)
+
+BUNDLED WITH
+   2.3.9

data/README.md

@@ -2,6 +2,10 @@
 
 The purpose of documentation zero is to generate a scaffold for rails api documentations using markdown.
 
+## Example
+
+You can see an example of the generated documentation [here](.documentation_api/README.md)
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -20,11 +24,11 @@ rails generate documentation:readme
 rails generate documentation:scaffold posts title:string body:text published:boolean
 ```
 
-Add ```- [Posts](.documentation-api/sections/posts.md)``` to API endpoints section.
+Add ```- [Posts](sections/posts.md)``` to API endpoints section.
 
 ## Development
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
 ## Contributing
 

data/lib/documentation_zero/version.rb

@@ -1,3 +1,3 @@
 module DocumentationZero
-  VERSION = "0.0.1"
+  VERSION = "0.0.4"
 end

data/lib/generators/documentation/scaffold/templates/resource.md.tt

@@ -10,7 +10,7 @@ Endpoints:
 
 ## Get <%= human_name.pluralize.downcase %>
 
-- `GET /<%= plural_name %>.json` will return a [paginated list](../readme.md#pagination) of <%= human_name.pluralize.downcase %>.
+- `GET /<%= plural_name %>.json` will return a [paginated list](../README.md#pagination) of <%= human_name.pluralize.downcase %>.
 
 <!--
 _Optional query parameters_:
@@ -55,8 +55,8 @@ This endpoint will return `200 OK` with the current JSON representation of the <
 
 _Optional parameters_:
 
-<% attributes.each do |attribute| -%>
-* `<%= attribute.column_name %>` - attribute from <%= human_name.downcase %>.
+<% attributes_names.each do |attribute| -%>
+* `<%= attribute %>` - attribute from <%= human_name.downcase %>.
 <% end -%>
 
 ## Delete <%= human_name.downcase %>
@@ -68,10 +68,18 @@ This endpoint will return `204 No Content` if successful. No parameters are requ
 ---
 
 ## Model
-```javascript
+```json
 {
 <% attributes.each do |attribute| -%>
-  <%= attribute.column_name %>: "<%= attribute.type %>",
+<% if attribute.password_digest? -%>
+  "password_digest": "string",
+<% elsif attribute.token? -%>
+  "<%= attribute.column_name %>": "string",
+<% elsif attribute.reference? -%>
+  "<%= attribute.column_name %>": "integer",
+<% elsif !attribute.virtual? -%>
+  "<%= attribute.column_name %>": "<%= attribute.type %>",
+<% end -%>
 <% end -%>
 }
 ```

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: documentation-zero
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.4
 platform: ruby
 authors:
 - Nixon
@@ -17,9 +17,12 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".documentation_api/README.md"
+- ".documentation_api/sections/posts.md"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
+- Gemfile.lock
 - LICENSE.txt
 - README.md
 - Rakefile