Make the generated API docs valid Swagger 2.0

The apidocs spec has been `pending 'Is not valid swagger at the moment'` for as
long as anyone remembers, so the document /api/v8/apidocs serves — the input to
swagger-ui and to any client generator pointed at it — has been free to drift.
Validating it against spec/resources/swagger-schema.json reported exactly three
errors, all of them malformed swagger metadata in controllers, none of them a
problem with the routes they describe.

Two path keys were missing their leading slash:

    api/v8/exercises/{exercise_id}/users/{user_id}/submissions
    api/v8/exercises/{exercise_id}/users/current/submissions

A Swagger 2.0 path key must begin with `/`; these two were the only offenders and
they were being dropped by tooling rather than merged with their siblings.

/api/v8/core/exercises/details declared its `ids` query parameter with a nested
`schema`. Only a body parameter may carry `schema`; every other location describes
its type inline, and an array must supply `items`. The parameter already had a
redundant `type: :array` next to the schema, so the fix is to keep that and move
`items` up beside it. `collectionFormat: csv` is now explicit because the action
reads the value with `split(',')`.

/api/v8/users/get_user_with_email had a query string embedded in its path key,
`/api/v8/users/get_user_with_email?email={email}`, and a `content` key in its 200
response, which is OpenAPI 3 and is not allowed in a Swagger 2.0 response object.
The route itself is fine — `get :get_user_with_email, on: :collection`, and the
action reads `params[:email]` — so the endpoint is unchanged and only its
description is corrected: the path key loses the query string and `email` becomes a
query parameter. That also fixes two dangling `$ref`s found while doing it. The
referenced `#/parameters/user_email` was never defined (the definition was named
`path_user_email`), so the parameter was silently absent from the rendered docs
altogether; it is now `query_user_email`, `in: query`, named `email` to match the
action. set_password_managed_by_courses_mooc_fi referenced a non-existent
`#/parameters/user_id` the same way and now points at `path_user_id`.

With those fixed the document validates, so the spec becomes a real test instead of
a pending one — the point of keeping it is that it now stops this from regressing.
It reports through `fully_validate` rather than the boolean `validate` so a future
failure names the offending property instead of just saying `false` is not truthy.

A second example asserts no path key contains a `?`. The Swagger 2.0 JSON schema
matches path keys with `^/` only, so it accepted the get_user_with_email key and
flagged just the `content` alongside it; without this assertion the exact defect
that was fixed above could come back unnoticed.

Author: nygrenh

app/controllers/api/v8/apidocs_controller.rb

@@ -62,9 +62,9 @@ class ApidocsController < ActionController::Base
           key :required, true
           key :type, :integer
         end
-        parameter :path_user_email do
-          key :name, :user_email
-          key :in, :path
+        parameter :query_user_email do
+          key :name, :email
+          key :in, :query
           key :description, "User's email"
           key :required, true
           key :type, :string

app/controllers/api/v8/core/exercises/details_controller.rb

@@ -16,14 +16,12 @@ class DetailsController < Api::V8::BaseController
               parameter do
                 key :in, 'query'
                 key :name, 'ids'
-                schema do
-                  key :type, :array
-                  items do
-                    key :type, :integer
-                  end
-                end
-                key :type, :array
                 key :description, 'Exercise Ids'
+                key :type, :array
+                key :collectionFormat, 'csv'
+                items do
+                  key :type, :integer
+                end
               end
               response 200 do
                 key :description, 'Exercises in json'

app/controllers/api/v8/exercises/users/submissions_controller.rb

@@ -7,7 +7,7 @@ module Users
         class SubmissionsController < Api::V8::BaseController
           include Swagger::Blocks
 
-          swagger_path 'api/v8/exercises/{exercise_id}/users/{user_id}/submissions' do
+          swagger_path '/api/v8/exercises/{exercise_id}/users/{user_id}/submissions' do
             operation :get do
               key :description, 'Returns the submissions visible to the user in a json format'
               key :operationId, 'findUsersSubmissionsForExerciseById'
@@ -33,7 +33,7 @@ class SubmissionsController < Api::V8::BaseController
             end
           end
 
-          swagger_path 'api/v8/exercises/{exercise_id}/users/current/submissions' do
+          swagger_path '/api/v8/exercises/{exercise_id}/users/current/submissions' do
             operation :get do
               key :description, "Returns the current user's submissions for the exercise in a json format. The exercise is searched by id."
               key :operationId, 'findUsersOwnSubmissionsForExerciseById'

app/controllers/api/v8/users_controller.rb

@@ -62,7 +62,7 @@ class UsersController < Api::V8::BaseController
           key :operationId, 'setPasswordManagedByCoursesMoocFi'
           key :produces, ['application/json']
           key :tags, ['user']
-          parameter '$ref': '#/parameters/user_id'
+          parameter '$ref': '#/parameters/path_user_id'
           response 403, '$ref': '#/responses/error'
           response 404, '$ref': '#/responses/error'
           response 200 do
@@ -76,18 +76,17 @@ class UsersController < Api::V8::BaseController
         end
       end
 
-      swagger_path '/api/v8/users/get_user_with_email?email={email}' do
+      swagger_path '/api/v8/users/get_user_with_email' do
         operation :get do
           key :description, "Returns the user's id as upstream_id, user's courses.mooc.fi-id as id, email, first name and last name by user email"
           key :operationId, 'getUserInformationByEmail'
           key :produces, ['application/json']
           key :tags, ['user']
-          parameter '$ref': '#/parameters/user_email'
+          parameter '$ref': '#/parameters/query_user_email'
           response 403, '$ref': '#/responses/error'
           response 404, '$ref': '#/responses/error'
           response 200 do
             key :description, "User's courses.mooc.fi-id as id, email, first name, last name and id as upstream_id as json"
-            key :content, 'application/json'
             schema do
               key :title, :user
               key :required, [:user]

spec/controllers/api/v8/apidocs_controller_spec.rb

@@ -5,12 +5,21 @@
 
 describe Api::V8::ApidocsController, type: :controller do
   it 'json provided by controller should be valid swagger' do
-    pending 'Is not valid swagger at the moment'
     get :index
     json = response.body
 
     schema = File.join(Rails.root, 'spec', 'resources', 'swagger-schema.json')
-    validation = JSON::Validator.validate(schema, json)
-    expect(validation).to be_truthy
+    errors = JSON::Validator.fully_validate(schema, json)
+    expect(errors).to be_empty, -> { "Generated apidocs are not valid Swagger 2.0:\n#{errors.join("\n")}" }
+  end
+
+  # The Swagger 2.0 JSON schema only requires a path key to start with a slash, so it
+  # cannot catch a query string smuggled into the key. Query parameters belong in
+  # `parameters`, with `in: query`.
+  it 'declares no path containing a query string' do
+    get :index
+
+    paths = JSON.parse(response.body)['paths'].keys
+    expect(paths.grep(/\?/)).to be_empty
   end
 end