cleanup: Drop support for OpenAPI (Swagger) v2

.github/ISSUE_TEMPLATE/bug_report.md

@@ -29,6 +29,5 @@ The version of are you using for:
 * Ruby:
 
 ## Relates to which version of OAS (OpenAPI Specification)
-- [ ] OAS2
 - [ ] OAS3
 - [ ] OAS3.1

.github/ISSUE_TEMPLATE/feature_request.md

@@ -24,6 +24,5 @@ A clear and concise description of any alternative solutions or features you've
 Add any other context or screenshots about the feature request here.
 
 ## Relates to which version of OAS (OpenAPI Specification)
-- [ ] OAS2
 - [ ] OAS3
 - [ ] OAS3.1

.github/pull_request_template.md

@@ -9,7 +9,6 @@ A clear and concise description of what the solution is.
 * [ANOTHER LINK TO RELEVANT OPEN API SPECS PAGE](https://spec.openapis.org/oas/v3.1.0#schema)
 
 ### The changes I made are compatible with:
-- [ ] OAS2
 - [ ] OAS3
 - [ ] OAS3.1
 

README.md

@@ -5,7 +5,7 @@ rswag
 [![Build Status](https://github.com/rswag/rswag/actions/workflows/ruby.yml/badge.svg?branch=master)](https://github.com/rswag/rswag/actions/workflows/ruby.yml?query=branch%3Amaster+)
 [![Maintainability](https://api.codeclimate.com/v1/badges/1175b984edc4610f82ab/maintainability)](https://codeclimate.com/github/rswag/rswag/maintainability)
 
-OpenApi 3.0 and Swagger 2.0 compatible!
+OpenApi 3.0 compatible!
 
 Seeking maintainers! Got a pet-bug that needs fixing? Just let us know in your issue/pr that you'd like to step up to help.
 
@@ -33,7 +33,7 @@ Once you have an API that can describe itself in Swagger, you've opened the trea
       - [Formatting the description literals:](#formatting-the-description-literals)
     - [Specifying/Testing API Security](#specifyingtesting-api-security)
   - [Configuration & Customization](#configuration--customization)
-    - [Output Location for Generated Swagger Files](#output-location-for-generated-swagger-files)
+    - [Output Location for Generated OpenAPI Files](#output-location-for-generated-openapi-files)
     - [Input Location for Rspec Tests](#input-location-for-rspec-tests)
     - [Referenced Parameters and Schema Definitions](#referenced-parameters-and-schema-definitions)
     - [Request examples](#request-examples)
@@ -44,10 +44,10 @@ Once you have an API that can describe itself in Swagger, you've opened the trea
       - [Dry Run Option](#dry-run-option)
       - [Running tests without documenting](#running-tests-without-documenting)
         - [rswag helper methods](#rswag-helper-methods)
-    - [Route Prefix for Swagger JSON Endpoints](#route-prefix-for-swagger-json-endpoints)
-    - [Root Location for Swagger Files](#root-location-for-swagger-files)
-    - [Dynamic Values for Swagger JSON](#dynamic-values-for-swagger-json)
-    - [Custom Headers for Swagger Files](#custom-headers-for-swagger-files)
+    - [Route Prefix for OpenAPI JSON Endpoints](#route-prefix-for-openapi-json-endpoints)
+    - [Root Location for OpenAPI Files](#root-location-for-openapi-files)
+    - [Dynamic Values for OpenAPI JSON](#dynamic-values-for-openapi-json)
+    - [Custom Headers for OpenAPI Files](#custom-headers-for-openapi-files)
     - [Enable Swagger Endpoints for swagger-ui](#enable-swagger-endpoints-for-swagger-ui)
     - [Enable Simple Basic Auth for swagger-ui](#enable-simple-basic-auth-for-swagger-ui)
     - [Route Prefix for the swagger-ui](#route-prefix-for-the-swagger-ui)
@@ -242,7 +242,7 @@ end
 
 ### Support for oneOf, anyOf or AllOf schemas ###
 
-Open API 3.0 now supports more flexible schema validation with the ```oneOf```, ```anyOf``` and ```allOf``` directives. rswag will handle these definitions and validate them properly.
+OpenAPI 3.0 supports more flexible schema validation with the ```oneOf```, ```anyOf``` and ```allOf``` directives. rswag will handle these definitions and validate them properly.
 
 
 Notice the ```schema``` inside the ```response``` section. Placing a ```schema``` method inside the response will validate (and fail the tests)
@@ -277,7 +277,7 @@ This automatic schema validation is a powerful feature of rswag.
 
 ### Global Metadata ###
 
-In addition to paths, operations and responses, Swagger also supports global API metadata. When you install rswag, a file called _swagger_helper.rb_ is added to your spec folder. This is where you define one or more Swagger documents and provide global metadata. Again, the format is based on Swagger so most of the global fields supported by the top level ["Swagger" object](http://swagger.io/specification/#swaggerObject) can be provided with each document definition. As an example, you could define a Swagger document for each version of your API and in each case specify a title, version string. In Open API 3.0 the pathing and server definitions have changed a bit [Swagger host/basePath](https://swagger.io/docs/specification/api-host-and-base-path/):
+In addition to paths, operations and responses, Swagger also supports global API metadata. When you install rswag, a file called _swagger_helper.rb_ is added to your spec folder. This is where you define one or more Swagger documents and provide global metadata. Again, the format is based on Swagger so most of the global fields supported by the top level ["Swagger" object](http://swagger.io/specification/#swaggerObject) can be provided with each document definition. As an example, you could define a Swagger document for each version of your API and in each case specify a title, version string.
 
 ```ruby
 # spec/swagger_helper.rb
@@ -364,7 +364,7 @@ you should use the following syntax, making sure there is no whitespace at the s
 
 Swagger allows for the specification of different security schemes and their applicability to operations in an API.
 To leverage this in rswag, you define the schemes globally in _swagger_helper.rb_ and then use the "security" attribute at the operation level to specify which schemes, if any, are applicable to that operation.
-Swagger supports :basic, :bearer, :apiKey and :oauth2 and :openIdConnect scheme types. See [the spec](https://swagger.io/docs/specification/authentication/) for more info, as this underwent major changes between Swagger 2.0 and Open API 3.0
+Swagger supports :basic, :bearer, :apiKey and :oauth2 and :openIdConnect scheme types. See [the spec](https://swagger.io/docs/specification/authentication/) for more info.
 
 ```ruby
 # spec/swagger_helper.rb
@@ -373,7 +373,6 @@ RSpec.configure do |config|
 
   config.swagger_docs = {
     'v1/swagger.json' => {
-      ...  # note the new Open API 3.0 compliant security structure here, under "components"
       components: {
         securitySchemes: {
           basic_auth: {
@@ -453,7 +452,7 @@ The steps described above will get you up and running with minimal setup. Howeve
 | __rswag-api__   | Rails Engine that exposes your Swagger files as JSON endpoints                                                               | _config/initializers/rswag_api.rb, config/routes.rb_ |
 | __rswag-ui__    | Rails Engine that includes [swagger-ui](https://github.com/swagger-api/swagger-ui) and powers it from your Swagger endpoints | _config/initializers/rswag-ui.rb, config/routes.rb_  |
 
-### Output Location for Generated Swagger Files ###
+### Output Location for Generated OpenAPI Files ###
 
 You can adjust this in the _swagger_helper.rb_ that's installed with __rswag-specs__:
 
@@ -601,7 +600,7 @@ 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:
+Rswag will validate your response headers with those header objects and inject them into the generated OpenAPI spec:
 
 ```ruby
 # spec/requests/comments_spec.rb
@@ -639,7 +638,7 @@ end
 
 ### Response examples ###
 
-You can provide custom response examples to the generated swagger file by calling the method `examples` inside the response block:
+You can provide custom response examples to the generated OpenAPI spec by calling the method `examples` inside the response block:
 However, auto generated example responses are now enabled by default in rswag. See below.
 
 ```ruby
@@ -772,7 +771,7 @@ In the above example, we see methods ```request_body_json``` ```request_body_pla
 These methods can be used to describe json, plain text and xml body. They are just wrapper methods to setup posting JSON, plain text or xml into your endpoint.
 The simplest most common usage is for json formatted body to use the schema: to specify the location of the schema for the request body
 and the examples: :blog which will create a named example "blog" under the "requestBody / content / application/json / examples" section.
-Again, documenting request response examples changed in Open API 3.0. The example above would generate a swagger.json snippet that looks like this:
+Again, documenting request response examples changed in OpenAPI 3.0. The example above would generate a swagger.json snippet that looks like this:
 
 ```json
         ...
@@ -782,7 +781,7 @@ Again, documenting request response examples changed in Open API 3.0. The exampl
             "application/json": {
               "examples": {
                 "blog": {  // takes the name from  examples: :blog above
-                  "value": {  //this is open api 3.0 structure -> https://swagger.io/docs/specification/adding-examples/
+                  "value": {  // this is OpenAPI 3.0 structure -> https://swagger.io/docs/specification/adding-examples/
                     "blog": { // here is the actual JSON payload that is submitted to the service, and shows up in swagger UI as an example
                       "title": "foo",
                       "content": "bar"
@@ -815,9 +814,9 @@ This ```let``` value is used in the integration test to run the test AND capture
 
 ##### rswag response examples #####
 
-In the same way that requestBody examples can be captured and injected into the swagger output, response examples can also be captured.
-Using the above example, when the integration test is run - the swagger would include the following snippet providing more useful real world examples
-capturing the response from the execution of the integration test. Again 3.0 swagger changed the structure of how these are documented.
+In the same way that requestBody examples can be captured and injected into the output, response examples can also be captured.
+Using the above example, when the integration test is run - the OpenAPI spec would include the following snippet providing more useful real world examples
+capturing the response from the execution of the integration test.
 
 ```json
        ...  "responses": {
@@ -857,9 +856,9 @@ capturing the response from the execution of the integration test. Again 3.0 swa
         }
 ```
  -->
-### Route Prefix for Swagger JSON Endpoints ###
+### Route Prefix for OpenAPI 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_:
+The functionality to expose OpenAPI 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_:
 
 ```ruby
 TestApp::Application.routes.draw do
@@ -869,48 +868,48 @@ TestApp::Application.routes.draw do
 end
 ```
 
-Assuming a Swagger file exists at <swagger_root>/v1/swagger.json, this configuration would expose the file as the following JSON endpoint:
+Assuming a OpenAPI file exists at <openapi_root>/v1/openapi.json, this configuration would expose the file as the following JSON endpoint:
 
 ```
-GET http://<hostname>/your-custom-prefix/v1/swagger.json
+GET http://<hostname>/your-custom-prefix/v1/openapi.json
 ```
 
-### Root Location for Swagger Files ###
+### Root Location for OpenAPI Files ###
 
 You can adjust this in the _rswag_api.rb_ initializer that's installed with __rspec-api__:
 
 ```ruby
 Rswag::Api.configure do |c|
-  c.swagger_root = Rails.root.to_s + '/your-custom-folder-name'
+  c.openapi_root = Rails.root.to_s + '/your-custom-folder-name'
   ...
 end
 ```
 
-__NOTE__: If you're using rswag-specs to generate Swagger files, you'll want to ensure they both use the same &lt;swagger_root&gt;. The reason for separate settings is to maintain independence between the two gems. For example, you could install rswag-api independently and create your Swagger files manually.
+__NOTE__: If you're using rswag-specs to generate OpenAPI files, you'll want to ensure they both use the same &lt;openapi_root&gt;. The reason for separate settings is to maintain independence between the two gems. For example, you could install rswag-api independently and create your OpenAPI files manually.
 
-### Dynamic Values for Swagger JSON ##
+### Dynamic Values for OpenAPI JSON ##
 
-There may be cases where you need to add dynamic values to the Swagger JSON that's returned by rswag-api. For example, you may want to provide an explicit host name. Rather than hardcoding it, you can configure a filter that's executed prior to serializing every Swagger document:
+There may be cases where you need to add dynamic values to the OpenAPI JSON that's returned by rswag-api. For example, you may want to provide an explicit host name. Rather than hardcoding it, you can configure a filter that's executed prior to serializing every OpenAPI document:
 
 ```ruby
 Rswag::Api.configure do |c|
   ...
 
-  c.swagger_filter = lambda { |swagger, env| swagger['host'] = env['HTTP_HOST'] }
+  c.openapi_filter = lambda { |openapi, env| openapi['host'] = env['HTTP_HOST'] }
 end
 ```
 
 Note how the filter is passed the rack env for the current request. This provides a lot of flexibility. For example, you can assign the "host" property (as shown) or you could inspect session information or an Authorization header and remove operations based on user permissions.
 
-### Custom Headers for Swagger Files ###
+### Custom Headers for OpenAPI Files ###
 
-You can specify custom headers for serving your generated Swagger JSON. For example you may want to force a specific charset for the 'Content-Type' header. You can configure a hash of headers to be sent with the request:
+You can specify custom headers for serving your generated OpenAPI JSON. For example you may want to force a specific charset for the 'Content-Type' header. You can configure a hash of headers to be sent with the request:
 
 ```ruby
 Rswag::Api.configure do |c|
   ...
 
-  c.swagger_headers = { 'Content-Type' => 'application/json; charset=UTF-8' }
+  c.openapi_headers = { 'Content-Type' => 'application/json; charset=UTF-8' }
 end
 ```
 
@@ -923,8 +922,8 @@ You can update the _rswag_ui.rb_ initializer, installed with rswag-ui, to specif
 
 ```ruby
 Rswag::Ui.configure do |c|
-  c.swagger_endpoint '/api-docs/v1/swagger.json', 'API V1 Docs'
-  c.swagger_endpoint '/api-docs/v2/swagger.json', 'API V2 Docs'
+  c.openapi_endpoint '/api-docs/v1/openapi.json', 'API V1 Docs'
+  c.openapi_endpoint '/api-docs/v2/openapi.json', 'API V2 Docs'
 end
 ```
 
@@ -982,4 +981,4 @@ docker pull swaggerapi/swagger-editor
 docker run -d -p 80:8080 swaggerapi/swagger-editor
 ```
 This will run the swagger editor in the docker daemon and can be accessed
-at ```http://localhost```. From here, you can use the UI to load the generated swagger.json to validate the output.
+at ```http://localhost```. From here, you can use the UI to load the generated openapi.json to validate the output.

rswag-api/lib/generators/rswag/api/install/templates/rswag_api.rb

@@ -4,7 +4,7 @@
   # This is used by the Swagger middleware to serve requests for API descriptions
   # NOTE: If you're using rswag-specs to generate Swagger, you'll need to ensure
   # that it's configured to generate files in the same folder
-  c.swagger_root = Rails.root.to_s + '/swagger'
+  c.openapi_root = Rails.root.to_s + '/openapi'
 
   # Inject a lambda function to alter the returned Swagger prior to serialization
   # The function will have access to the rack env for the current request

rswag-api/lib/rswag/api/configuration.rb

@@ -1,11 +1,11 @@
 module Rswag
   module Api
     class Configuration
-      attr_accessor :swagger_root, :swagger_filter, :swagger_headers
+      attr_accessor :openapi_root, :openapi_filter, :openapi_headers
 
-      def resolve_swagger_root(env)
+      def resolve_openapi_root(env)
         path_params = env['action_dispatch.request.path_parameters'] || {}
-        path_params[:swagger_root] || swagger_root
+        path_params[:openapi_root] || openapi_root
       end
     end
   end

rswag-api/lib/rswag/api/middleware.rb

@@ -13,14 +13,14 @@ def initialize(app, config)
 
       def call(env)
         path = env['PATH_INFO']
-        filename = "#{@config.resolve_swagger_root(env)}/#{path}"
+        filename = "#{@config.resolve_openapi_root(env)}/#{path}"
 
         if env['REQUEST_METHOD'] == 'GET' && File.file?(filename)
-          swagger = parse_file(filename)
-          @config.swagger_filter.call(swagger, env) unless @config.swagger_filter.nil?
+          openapi = parse_file(filename)
+          @config.openapi_filter.call(openapi, env) unless @config.openapi_filter.nil?
           mime = Rack::Mime.mime_type(::File.extname(path), 'text/plain')
-          headers = { 'Content-Type' => mime }.merge(@config.swagger_headers || {})
-          body = unload_swagger(filename, swagger)
+          headers = { 'Content-Type' => mime }.merge(@config.openapi_headers || {})
+          body = unload_openapi(filename, openapi)
 
           return [
             '200',
@@ -50,11 +50,11 @@ def load_json(filename)
         JSON.parse(File.read(filename))
       end
 
-      def unload_swagger(filename, swagger)
+      def unload_openapi(filename, openapi)
         if /\.ya?ml$/ === filename
-          YAML.dump(swagger)
+          YAML.dump(openapi)
         else
-          JSON.dump(swagger)
+          JSON.dump(openapi)
         end
       end
     end

rswag-api/spec/rswag/api/fixtures/openapi/v1/openapi.yml

@@ -0,0 +1,12 @@
+openapi: 3.0.0
+info:
+  version: 1.0.0
+  title: API V1
+  description: A sample API to illustrate OpenAPI concepts
+paths:
+  /list:
+    get:
+      description: Returns a list of stuff
+      responses:
+        '200':
+          description: Successful response