Update README for response headers and examples

README.md

@@ -243,6 +243,47 @@ describe 'Blogs API' do
 end
 ```
 
+### Response headers ###
+
+In Rswag, you could use `header` method inside the response block to specify header objects for this response. Rswag will validate your response headers with those header objects and inject them into the generated swagger file:
+
+```ruby
+# spec/integration/comments_spec.rb
+describe 'Blogs API' do
+
+  path '/blogs/{blog_id}/comments' do
+
+    post 'Creates a comment' do
+
+      response 422, 'invalid request' do
+        header 'X-Rate-Limit-Limit', type: :integer, description: 'The number of allowed requests in the current period'
+        header 'X-Rate-Limit-Remaining', type: :integer, description: 'The number of remaining requests in the current period'
+  ...
+end
+```
+
+### Response examples ###
+
+You can provide custom response examples to the generated swagger file by calling the method `response_examples` inside the response block:
+
+```ruby
+# spec/integration/blogs_spec.rb
+describe 'Blogs API' do
+
+  path '/blogs/{blog_id}' do
+
+    get 'Retrieves a blog' do
+
+      response 200, 'blog found' do
+        response_examples 'application/json' => {
+            id: 1,
+            title: 'Hello world!',
+            content: '...'
+          }
+  ...
+end
+```
+
 ### Route Prefix for Swagger JSON Endpoints ###
 
 The functionality to expose Swagger files, such as those generated by rswag-specs, as JSON endpoints is implemented as a Rails Engine. As with any Engine, you can change it's mount prefix in _routes.rb_: