Skip to content

Commit

Permalink
update post
Browse files Browse the repository at this point in the history
  • Loading branch information
@mangege
mangege committed Jun 11, 2016
1 parent 36cd125 commit d8c3838
Show file tree
Hide file tree
Showing 2 changed files with 234 additions and 0 deletions.
234 changes: 234 additions & 0 deletions _posts/2016-05-23-1.md
View file
Expand Up @@ -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)

未完待续...
Binary file added favicon.ico
View file
Binary file not shown.

0 comments on commit d8c3838

Please sign in to comment.