1+ # @resource Tags
2+ #
3+ # @resource_path /tags
4+ #
5+ # API for tag management.
6+ #
17class TagsController < ApplicationController
2- # Show a single tag
3- # Example:
4- # `curl -v -H "Content-type: application/json" 'http://localhost:3000/api/v1/tags/paranoid.json'
8+
9+ ##
10+ # @summary Fetches a single tag by its name {name}.
11+ #
12+ # @notes Example: `curl -v -H "Content-type: application/json" 'http://localhost:3000/api/v1/tags/paranoid.json'
13+ #
14+ # @path [GET] /tags/{name}.json
15+ #
16+ # @response_type [Tag]
17+ #
18+ # @error_message 304 The content has not changed in relation to the request ETag / If-Modified-Since
19+ # @error_message 404 A tag of the provided name cannot be found
20+ #
521 def show
622 not_found_with_max_age ( caching_time ) and return unless ( @tag = Tag . find_by_name ( params [ :id ] ) )
723 Rails . logger . debug "Tag with name #{ @tag . name } #{ @tag . inspect }
@@ -13,25 +29,46 @@ def show
1329 expires_in caching_time , public : true
1430 end
1531
16- # List all tags (can be filtered by "item_id" parameter)
17- # Example:
18- # `curl -v -H "Content-type: application/json" 'http://localhost:3000/api/v1/tags.json'`
32+ ##
33+ # @summary Fetches all tags (filterable by tags for a given {item_id})
34+ #
35+ # @notes Example: `curl -v -H "Content-type: application/json" 'http://localhost:3000/api/v1/tags.json'`
36+ #
37+ # @path [GET] /tags.json
38+ #
39+ # @parameter [integer] item_id(query) ID of the tagged inventory item by which to filter the tags
40+ #
41+ # @response_type [array<Tag>]
42+ #
43+ # @error_message 304 The content has not changed in relation to the request ETag / If-Modified-Since
44+ #
1945 def index
2046 item_id = params [ :item_id ] . to_i
2147 all_tags = ( item_id > 0 ) ? Tag . joins ( :tagged_items ) . where ( tagged_items : { item_id : item_id } ) : Tag . all
2248 return json_response ( [ ] ) unless newest_tag = all_tags . sort_by ( &:updated_at ) . last
23- Rails . logger . info "newest_tag is #{ newest_tag . inspect }
49+ Rails . logger . info "newest_tag is #{ newest_tag . inspect } , all tags are of size: #{ all_tags . count }
2450 render_if_stale ( all_tags , last_modified : newest_tag . updated_at . utc , etag : newest_tag ) do |tag_presenters |
2551 tag_presenters . map ( &:hash )
2652 end
2753 # explicitly setting the Cache-Control response header to public and max-age, to make the response cachable by proxy caches
2854 expires_in caching_time , public : true
2955 end
3056
31- # Create a new tag.
32- # Example:
33- # `curl -v -H "Content-type: application/json" -X POST 'http://localhost:3000/api/v1/tags.json' \
34- # -d '{"name":"android"}'`
57+ ##
58+ # @summary Creates a new tag by the given name
59+ #
60+ # @notes Example: `curl -v -H "Content-type: application/json" -X POST 'http://localhost:3000/api/v1/tags.json' \
61+ # -d '{"name":"android"}'`
62+ #
63+ # @path [POST] /tags.json
64+ #
65+ # @parameter [string] name(required,body) Name (unique) of the tag to be created
66+ #
67+ # @response_type [string]
68+ #
69+ # @error_message 409 Conflict, a Tag with given name already exists
70+ # @error_message 422 Unprocessable Entity, the tag cannot be created because there were errors saving
71+ #
3572 def create
3673 tag = Tag . find_or_initialize_by ( params . slice ( :name ) )
3774 render ( json : { error : "Tag with name #{ params [ :name ] } } , status : :conflict ) and return unless tag . new_record?
@@ -43,10 +80,21 @@ def create
4380 end
4481 end
4582
46- # Update an existing tag.
47- # Example:
48- # `curl -v -H "Content-type: application/json" -X PUT 'http://localhost:3000/api/v1/tags/android.json' \
49- # -d '{"name":"paranoid"}'`
83+ ##
84+ # @summary Updates an existing tag's name, referenced by its current name
85+ #
86+ # @notes Example: `curl -v -H "Content-type: application/json" -X PUT 'http://localhost:3000/api/v1/tags/android.json' \
87+ # -d '{"name":"paranoid"}'`
88+ #
89+ # @path [PUT] /tags/{name}.json
90+ #
91+ # @parameter [string] new_name(required,body) The tag's new name
92+ #
93+ # @response_type [string]
94+ #
95+ # @error_message 404 Not Found, a Tag with given name does not exists
96+ # @error_message 422 Unprocessable Entity, the tag cannot be updated because there were errors saving
97+ #
5098 def update
5199 tag = Tag . find_by_name ( params [ :id ] )
52100 render ( json : { error : "Tag with name #{ params [ :id ] } } , status : :not_found ) and return if tag . nil?
@@ -59,9 +107,18 @@ def update
59107 end
60108 end
61109
62- # Delete a tag
63- # Example:
64- # `curl -v -H "Content-type: application/json" -X DELETE 'http://localhost:3000/api/v1/tags/paranoid.json'`
110+ ##
111+ # @summary Deletes an existing tag referenced by its name
112+ #
113+ # @notes Example: `curl -v -H "Content-type: application/json" -X DELETE 'http://localhost:3000/api/v1/tags/paranoid.json'`
114+ #
115+ # @path [DELETE] /tags/{name}.json
116+ #
117+ # @response_type [string]
118+ #
119+ # @error_message 404 A tag of the provided name cannot be found
120+ # @error_message 422 Unprocessable Entity, the tag cannot be deleted because there were errors destroying it
121+ #
65122 def destroy
66123 tag = Tag . find_by_name ( params [ :id ] )
67124 render ( json : { error : "Tag with name #{ params [ :id ] } } , status : :not_found ) and return if tag . nil?
0 commit comments