从RSpec请求规范生成OpenAPI模式-Ruby开发

  • C3_789357
    了解作者
  • 253.2KB
    文件大小
  • zip
    文件格式
  • 0
    收藏次数
  • VIP专享
    资源类型
  • 0
    下载次数
  • 2022-05-07 14:59
    上传日期
根据RSpec请求规范生成OpenAPI架构。 rspec-openapi根据RSpec请求规范生成OpenAPI架构。 这是什么? 有一些宝石可以根据RSpec请求规范生成OpenAPI规范。 但是,它们需要专用于这些gem的特殊DSL,并且我们无法按原样重用现有的请求规范。 与这些现有的gem不同,rspec-openapi可以从请求规范中生成OpenAPI规范,而无需任何特殊的DSL。 此外,rspec-openapi在将自动更改合并到OpenAPI规范时会保留手动修改的内容。
rspec-openapi-master.zip
内容介绍
# rspec-openapi ![test](https://github.com/k0kubun/rspec-openapi/workflows/test/badge.svg) Generate OpenAPI schema from RSpec request specs. ## What's this? There are some gems which generate OpenAPI specs from RSpec request specs. However, they require a special DSL specific to these gems, and we can't reuse existing request specs as they are. Unlike such [existing gems](#links), rspec-openapi can generate OpenAPI specs from request specs without requiring any special DSL. Furthermore, rspec-openapi keeps manual modifications when it merges automated changes to OpenAPI specs in case we can't generate everything from request specs. ## Installation Add this line to your application's Gemfile: ```ruby gem 'rspec-openapi', group: :test ``` ## Usage Run rspec with OPENAPI=1 to generate `doc/openapi.yaml` for your request specs. ```bash $ OPENAPI=1 rspec ``` ### Example Let's say you have [a request spec](./spec/requests/rails/tables_spec.rb) like this: ```rb RSpec.describe 'Tables', type: :request do describe '#index' do it 'returns a list of tables' do get '/tables', params: { page: '1', per: '10' }, headers: { authorization: 'k0kubun' } expect(response.status).to eq(200) end it 'does not return tables if unauthorized' do get '/tables' expect(response.status).to eq(401) end end # ... end ``` If you run the spec with `OPENAPI=1`, ``` OPENAPI=1 rspec spec/requests/tables_spec.rb ``` It will generate [`doc/openapi.yaml` file](./spec/rails/doc/openapi.yaml) like: ```yml openapi: 3.0.3 info: title: rspec-openapi paths: "/tables": get: summary: index tags: - Table parameters: - name: page in: query schema: type: integer example: 1 - name: per in: query schema: type: integer example: 10 responses: '200': description: returns a list of tables content: application/json: schema: type: array items: type: object properties: id: type: integer name: type: string # ... ``` and the schema file can be used as an input of [Swagger UI](https://github.com/swagger-api/swagger-ui) or [Redoc](https://github.com/Redocly/redoc). ![Redoc example](./spec/rails/doc/screenshot.png) ### Configuration The following configurations are optional. ```rb # Change the path to generate schema from `doc/openapi.yaml` RSpec::OpenAPI.path = 'doc/schema.yaml' # Disable generating `example` RSpec::OpenAPI.enable_example = false # Change `info.version` RSpec::OpenAPI.application_version = '1.0.0' # Generate a comment on top of a schema file RSpec::OpenAPI.comment = <<~EOS This file is auto-generated by rspec-openapi https://github.com/k0kubun/rspec-openapi When you write a spec in spec/requests, running the spec with `OPENAPI=1 rspec` will update this file automatically. You can also manually edit this file. EOS # Generate a custom description, given an RSpec example RSpec::OpenAPI.description_builder = -> (example) { example.description } ``` ### How can I add information which can't be generated from RSpec? rspec-openapi tries to keep manual modifications as much as possible when generating specs. You can directly edit `doc/openapi.yaml` as you like without spoiling the automatic generation capability. ### Can I exclude specific specs from OpenAPI generation? Yes, you can specify `openapi: false` to disable the automatic generation. ```rb RSpec.describe '/resources', type: :request, openapi: false do # ... end # or RSpec.describe '/resources', type: :request do it 'returns a resource', openapi: false do # ... end end ``` ## Project status Beta Basic features are there, and some people are already using this. ### Current limitation * Generating a JSON file is not supported yet ### Other missing features with notes * Delete obsoleted endpoints * Give up, or at least make the feature optional? * Running all to detect obsoleted endpoints is sometimes not realistic anyway. * Intelligent merges * To maintain both automated changes and manual edits, the schema merge needs to be intelligent. * We'll just deep-reverse-merge schema for now, but if there's a $ref for example, modifications there should be rerouted to the referenced object. * A type could be an array of all possible types when merged. ## Links Existing RSpec plugins which have OpenAPI integration: * [zipmark/rspec\_api\_documentation](https://github.com/zipmark/rspec_api_documentation) * [rswag/rswag](https://github.com/rswag/rswag) * [drewish/rspec-rails-swagger](https://github.com/drewish/rspec-rails-swagger) ## Acknowledgements This gem was heavily inspired by the following gem: * [r7kamura/autodoc](https://github.com/r7kamura/autodoc) ## License The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
评论
    相关推荐
    • trailblazer:Ruby的高级架构
      Trailblazer为Ruby框架提供了新的高级抽象。 它轻柔地执行封装,直观的代码结构,并以功能性思维方式对复杂的业务工作流进行建模。 文献资料 本文档讨论Trailblazer 2.1。 有关新增功能的概述。 我们正在开发几个新...
    • oxford_dictionary:牛津字典API的Ruby包装器
      Ruby包装器使用 入门 $ gem install oxford_dictionary # To use in your script/application require 'oxford_dictionary' 注册API密钥后,请设置客户端: client = OxfordDictionary :: Client . new ( app_id ...
    • Ruby_向ruby之父学程序设计(第二版)(经典入门)
      第一部分:通过简单的Ruby程序来介绍程序的基本架构。  第二部分:介绍基础语法规则,以及类、模块等面向对象程序设计的思考方法与用词。   第三部分:对一些基础类逐一介绍其功能与用法。 第四部分:介绍一些...
    • 为使用和弦输入的ANSI键盘设计的Rime Nihongo输入架构。-Ruby开发
      日本和弦是一款为ANSI、ISO、60%、40% 键盘设计的多键并击输入日本语的方法, 日本和弦日本语コード配方:℞ nihonchord Rime 日本和弦输入方案简介日本和弦是一款为ANSI 、ISO、60%、40% 键盘设计的多键并击输入...
    • ruby2600:一个实验性的 Atari:trade_mark: 2600 模拟器,100% 用 Ruby 编写
      这些展示了一般架构和基本原理。 当前状态 没有明显的毛刺工作游戏包括: 陷阱! 太空侵略者 河流突袭 吃豆人 网球 大金刚 您可以加载大多数 2K 和 4K 推车并试用它们。 速度非常低:在 2.3Ghz 的计算机上大约 ...
    • dotenv-schema:为 dotenv 定义架构
      dotenv 模式 Dotenv-schema 使模式化。 安装 编写.env和.env_schema : $ cat .env ...DB_PORT=3306 $ cat .env_schema DB_HOST: ...Sinatra 或Plain ol' Ruby $ gem install dotenv require 'dotenv-
    • parametric:Ruby应用程序的声明式输入模式
      Ruby对象中声明性地定义数据模式,并使用它们将白名单,验证或转换为程序的输入。 对于构建自定义API,搜索或表单对象很有用。 或者可以替代Rails的强参数(它不依赖于Rails,可以独立使用)。 架构图 定义架构 ...
    • Ruby-Trailblazer构建在Rails之让提供一个直观的代码结构并给你一个面向对象的架构
      Trailblazer 构建在Rails之让,提供一个直观的代码结构并给你一个面向对象的架构
    • 榴弹炮:基于Ruby的验收测试框架
      快速安装和配置完整的测试基础架构(不到5分钟)。 下方是优雅,直观且功能强大的Ruby语言。 可以选择您喜欢的BDD工具(Cucumber,RSpec或芜菁)。 与SauceLabs,Testingbot,BrowserStack,CrossBrowserTesting...
    • GaussDB_100_1.0.1-DATABASE-REDHAT-64bit.tar.gz
      guassdb100在redhat上安装包,单机部署的包,安装步骤请看我的文中介绍,经过大量实验搭建总结出来的文档