From d8c38384f0064088330b2bf4629ff6ca30d4ddd1 Mon Sep 17 00:00:00 2001 From: mangege Date: Sat, 11 Jun 2016 22:01:20 +0800 Subject: [PATCH] update post --- _posts/2016-05-23-1.md | 234 +++++++++++++++++++++++++++++++++++++++++ favicon.ico | Bin 0 -> 318 bytes 2 files changed, 234 insertions(+) create mode 100644 favicon.ico diff --git a/_posts/2016-05-23-1.md b/_posts/2016-05-23-1.md index 9d6ee37..b09724d 100644 --- a/_posts/2016-05-23-1.md +++ b/_posts/2016-05-23-1.md @@ -59,6 +59,240 @@ Ruby 里面的 Swagger 库我选 [Swagger::Blocks](https://github.com/fotinakis/ cd swagger_demo vi Gemfile # 编辑 Gemfile 文件,把第一行的 https://rubygems.org 替换成 https://gems.ruby-china.org bundle install + bundle exec rails g scaffold Article title:string text:text # 生成 Article 的 model 和 controller + bundle exec rake db:create db:migrate # 创建数据库，运行迁移 +代码: [https://github.com/mangege/swagger_demo/tree/step1](https://github.com/mangege/swagger_demo/tree/step1) +##### 2. 建立 swagger 初始文件 + + vi Gemfile # 添加 gem 'swagger-blocks' 到最后一行 + bundle install + bundle exec rails g controller Apidocs index + vi app/controllers/apidocs_controller.rb # 复制此段内容 https://github.com/fotinakis/swagger-blocks#docs-controller ,还需要再编辑此文件内容,最终请看仓库代码 + vi config/routes.rb # 删除掉 get 'apidocs/index' ，添加 resources :apidocs, only: [:index] + cd /tmp; git clone https://github.com/swagger-api/swagger-ui.git + cp -R /tmp/swagger-ui/dist ~/workspace/swagger_demo/public/ # 复制 swagger 的静态文件到 rails 项目的 public 目录下. + cd ~/workspace/swagger_demo/public/; mv dist swagger-ui # 重命名 dist 文件夹为 swagger-ui + vi public/swagger-ui/index.html # 替换 http://petstore.swagger.io/v2/swagger.json 为 /apidocs.json + +打开浏览器,访问 http://localhost:3000/swagger-ui/ 即可. + +代码: [https://github.com/mangege/swagger_demo/tree/step2](https://github.com/mangege/swagger_demo/tree/step2) + +#### 3. 为 Article 接口添加文档 + +按照 Swagger::Blocks 的示例,一般是在 model 或 controller 文件里写文档.但这样有可能导致 model 或 controller 文件行数过长. + +通过分析源码了解,我们随便建一个类也可以.所以我们在 app 目录下建立专门的 swagger 目录. + + mkdir app/swagger + vi config/application.rb # 添加 config.autoload_paths << Rails.root.join('app/swagger') ,改了此文件记得重启 rails server + + vi app/swagger/app/swagger/article_swagger.rb + +添加以下内容 + + class ArticleSwagger + include Swagger::Blocks + + swagger_schema :Article do + key :required, [:id] + property :id do + key :type, :integer + end + property :title do + key :type, :string + key :description, '标题' + end + property :text do + key :type, :string + key :description, '正文' + end + end + end + + vi app/controllers/apidocs_controller.rb # 在 SWAGGERED_CLASSES 添加 ArticleSwagger + + vi app/swagger/articles_controller_swagger.rb + +添加以下内容 + + class ArticlesControllerSwagger + include Swagger::Blocks + + swagger_path '/articles' do + operation :get do + key :description, 'article list' + key :operationId, 'articleIndex' + key :tags, [ + 'article' + ] + response 200 do + key :description, 'article response' + schema do + key :type, :array + items do + key :'$ref', :Article + end + end + end + response :default do + key :description, 'unexpected error' + schema do + key :'$ref', :ErrorModel + end + end + end + operation :post do + key :description, 'create article' + key :operationId, 'articleCreate' + key :tags, [ + 'article' + ] + parameter do + key :name, :article + key :in, :body + key :required, true + schema do + key :'$ref', :Article + end + end + response 200 do + key :description, 'article response' + schema do + key :'$ref', :Article + end + end + response :default do + key :description, 'unexpected error' + schema do + key :'$ref', :ErrorModel + end + end + end + end + + swagger_path '/articles/{id}' do + operation :get do + key :description, 'article show' + key :operationId, 'articleShow' + key :tags, [ + 'article' + ] + parameter do + key :name, :id + key :in, :path + key :required, true + key :type, :integer + end + response 200 do + key :description, 'article response' + schema do + key :'$ref', :Article + end + end + response :default do + key :description, 'unexpected error' + schema do + key :'$ref', :ErrorModel + end + end + end + operation :patch do + key :description, 'article update' + key :operationId, 'articleUpdate' + key :tags, [ + 'article' + ] + parameter do + key :name, :id + key :in, :path + key :required, true + key :type, :integer + end + parameter do + key :name, :article + key :in, :body + key :required, true + schema do + key :'$ref', :Article + end + end + response 200 do + key :description, 'article response' + schema do + key :'$ref', :Article + end + end + response :default do + key :description, 'unexpected error' + schema do + key :'$ref', :ErrorModel + end + end + end + operation :delete do + key :description, 'article destroy' + key :operationId, 'articleDestroy' + key :tags, [ + 'article' + ] + parameter do + key :name, :id + key :in, :path + key :required, true + key :type, :integer + end + response 204 do + schema do + key :type, :string + end + end + response :default do + key :description, 'unexpected error' + schema do + key :'$ref', :ErrorModel + end + end + end + end + end + + + vi app/swagger/error_model_swagger.rb + +添加以下内容 + + module ErrorModelSwagger + include Swagger::Blocks + + swagger_schema :ErrorModel do + key :description, '错误定义' + key :required, [:code, :message] + property :code do + key :type, :integer + key :description, '错误代码. 401 没有登录, 403 没有权限, 422 表单数据有误' + end + property :message do + key :type, :string + key :description, '错误消息' + end + property :errors do + key :type, :object + key :description, '错误详情. 键为出错的属性名.值为出错信息,值是字符串数组.' + end + end + + end + + vi app/controllers/apidocs_controller.rb # 在 SWAGGERED_CLASSES 添加 ErrorModelSwagger 和 ArticlesControllerSwagger + + vi app/controllers/application_controller.rb # 替换 exception 为 null_session ,注意,如果项目还有普通的web页面,不要把此改成 null_session ,而是新建一个 api_controller.rb 文件,在新建的文件里设置为 null_session ,然后所有的 api controller 都继承与它. + + +好了, Article 的 CRUD 操作的接口文档都已经编写完成,现在我们打开浏览器,访问 [http://localhost:3000/swagger-ui/](http://localhost:3000/swagger-ui/) ,即可通过 swagger ui 来阅读文档,并测试接口了. + +代码: [https://github.com/mangege/swagger_demo/tree/step3](https://github.com/mangege/swagger_demo/tree/step3) + 未完待续... diff --git a/favicon.ico b/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..71a41226a72c1d669bfa5cabc7c0575158ff6124 GIT binary patch literal 318 zcmbu3Jqp4=5QSerY%H=^NJ0v&LN4Gf#5$#C@C05Um2K`|m5>XhO;~HAt%X?(#7beE z*#R%$4DWsO!!84Olu9Y`2@(%j07yuRv?B4G<3O6vM7(2#VTd@6k)|n%qCl2q2!a4* zS)#6MjN^zXilDVdRaNM^4tbu#T1&5iH5C*`U-%L@znDGqW6XU?y!OMH`{u-Mt+_e; d*tF7b`$2Q{Hs;|b8~I1JzTmkNPTdiI*cX9vkHY`} literal 0 HcmV?d00001