From a6162f7c079d92f7cc6fc22ee07a043f1690e783 Mon Sep 17 00:00:00 2001 From: Adam Sharp Date: Thu, 18 Apr 2024 15:40:42 +0100 Subject: [PATCH] MAP-922: Add swagger docs for SAR (#2231) --- .../sre_swagger_docs_controller.rb | 11 ++ config/initializers/rswag-ui.rb | 1 + config/routes.rb | 2 + spec/swagger/swagger_doc_base.yaml | 100 ++++++++++++++++++ spec/swagger_helper.rb | 2 + swagger/base/swagger.yaml | 99 +++++++++++++++++ .../get_subject_access_request_responses.yaml | 34 +++++- 7 files changed, 248 insertions(+), 1 deletion(-) create mode 100644 app/controllers/sre_swagger_docs_controller.rb create mode 100644 spec/swagger/swagger_doc_base.yaml create mode 100644 swagger/base/swagger.yaml diff --git a/app/controllers/sre_swagger_docs_controller.rb b/app/controllers/sre_swagger_docs_controller.rb new file mode 100644 index 000000000..2051d3e07 --- /dev/null +++ b/app/controllers/sre_swagger_docs_controller.rb @@ -0,0 +1,11 @@ +# frozen_string_literal: true + +class SreSwaggerDocsController < ApplicationController + def swagger_ui + redirect_to '/api-docs/index.html' + end + + def open_api_json + render json: YAML.load_file('swagger/base/swagger.yaml') + end +end diff --git a/config/initializers/rswag-ui.rb b/config/initializers/rswag-ui.rb index bc0b779d2..3c77960f6 100644 --- a/config/initializers/rswag-ui.rb +++ b/config/initializers/rswag-ui.rb @@ -8,4 +8,5 @@ c.swagger_endpoint '/api-docs/v2/swagger.yaml', 'PECS4 API V2 Docs' c.swagger_endpoint '/api-docs/v1/swagger.yaml', 'PECS4 API V1 Docs' + c.swagger_endpoint '/api-docs/base/swagger.yaml', 'PECS4 API Base Docs' end diff --git a/config/routes.rb b/config/routes.rb index 5a78e0f62..ea4b108a9 100644 --- a/config/routes.rb +++ b/config/routes.rb @@ -6,6 +6,8 @@ if !Rails.env.production? || ENV['SERVE_API_DOCS'] mount Rswag::Ui::Engine => '/api-docs' mount Rswag::Api::Engine => '/api-docs' + get '/swagger-ui.html', to: 'sre_swagger_docs#swagger_ui' + get '/v3/api-docs', to: 'sre_swagger_docs#open_api_json' end get '/health', to: 'status#health', format: :json diff --git a/spec/swagger/swagger_doc_base.yaml b/spec/swagger/swagger_doc_base.yaml new file mode 100644 index 000000000..64036c736 --- /dev/null +++ b/spec/swagger/swagger_doc_base.yaml @@ -0,0 +1,100 @@ +--- +:basePath: "/api/base" +:openapi: 3.0.1 +:info: + :title: PECS4 Base API Docs + :version: v2 + :description: | + Book A Secure Move supplier and frontend API. +:consumes: + - application/vnd.api+json +:produces: + - application/vnd.api+json; version=2 +:servers: + - :url: http://localhost:3000/ + :description: Local development (localhost) + - :url: https://hmpps-book-secure-move-api-dev.apps.cloud-platform.service.justice.gov.uk/ + :description: Dev API + - :url: https://hmpps-book-secure-move-api-staging.apps.cloud-platform.service.justice.gov.uk/ + :description: Staging API + - :url: https://hmpps-book-secure-move-api-uat.apps.cloud-platform.service.justice.gov.uk/ + :description: UAT API + - :url: https://hmpps-book-secure-move-api-preprod.apps.cloud-platform.service.justice.gov.uk/a + :description: PreProd API + - :url: https://api.bookasecuremove.service.justice.gov.uk/ + :description: Production API +:security: + - :oauth2: [ ] +:components: + :securitySchemes: + :oauth2: + :type: :oauth2 + :flows: + :clientCredentials: + :authorizationUrl: "/oauth/authorize" + :tokenUrl: "/oauth/token/" + :scopes: { } + :schemas: + :Category: + :$ref: "../v2/category.yaml#/Category" +:paths: + "/subject-access-request": + get: + summary: "Returns all information related to the specified PRN" + tags: + - SubjectAccessRequest + consumes: + - application/vnd.api+json + parameters: + - "$ref": "../v2/accept_type_parameter.yaml#/Accept" + - "$ref": "../v1/content_type_parameter.yaml#/ContentType" + - "$ref": "../v2/accept_encoding.yaml#/AcceptEncoding" + - name: pnr + in: query + description: + Filters results to only include people identified by their police_national_computer. + This is a case insensitive search. + Either filter[police_national_computer], filter[prison_number] or filter[criminal_records_office] + are supported. + schema: + type: string + example: 07/1435713R + format: string + required: false + responses: + "200": + description: success + content: + application/vnd.api+json: + schema: + "$ref": "../v2/get_subject_access_request_responses.yaml#/200" + "204": + description: no content + content: + application/vnd.api+json: + schema: + "$ref": "../v2/get_subject_access_request_responses.yaml#/204" + "209": + description: unsuppoted parameter + content: + application/vnd.api+json: + schema: + "$ref": "../v2/get_subject_access_request_responses.yaml#/209" + "400": + description: bad request + content: + application/vnd.api+json: + schema: + "$ref": "../v2/get_subject_access_request_responses.yaml#/400" + "401": + description: unauthorized + content: + application/vnd.api+json: + schema: + "$ref": "../v2/get_subject_access_request_responses.yaml#/401" + "403": + description: forbidden + content: + application/vnd.api+json: + schema: + "$ref": "../v2/get_subject_access_request_responses.yaml#/403" diff --git a/spec/swagger_helper.rb b/spec/swagger_helper.rb index d3bf77e92..6ad5c4358 100644 --- a/spec/swagger_helper.rb +++ b/spec/swagger_helper.rb @@ -25,6 +25,7 @@ def load_swagger_yaml(*relative_path) swagger_doc_v1 = YAML.load_file('spec/swagger/swagger_doc_v1.yaml') swagger_doc_v2 = YAML.load_file('spec/swagger/swagger_doc_v2.yaml') + swagger_doc_base = YAML.load_file('spec/swagger/swagger_doc_base.yaml') swagger_doc_v2_integration = swagger_doc_v1.deep_dup @@ -33,6 +34,7 @@ def load_swagger_yaml(*relative_path) config.swagger_docs = { 'v1/swagger.yaml' => swagger_doc_v1, 'v2/swagger.yaml' => swagger_doc_v2_integration, + 'base/swagger.yaml' => swagger_doc_base, } # Specify the format of the output Swagger file when running 'rswag:specs:swaggerize'. diff --git a/swagger/base/swagger.yaml b/swagger/base/swagger.yaml new file mode 100644 index 000000000..38a5a56e3 --- /dev/null +++ b/swagger/base/swagger.yaml @@ -0,0 +1,99 @@ +--- +basePath: "/api/base" +openapi: 3.0.1 +info: + title: PECS4 Base API Docs + version: v2 + description: 'Book A Secure Move supplier and frontend API. + + ' +consumes: +- application/vnd.api+json +produces: +- application/vnd.api+json; version=2 +servers: +- url: http://localhost:3000/ + description: Local development (localhost) +- url: https://hmpps-book-secure-move-api-dev.apps.cloud-platform.service.justice.gov.uk/ + description: Dev API +- url: https://hmpps-book-secure-move-api-staging.apps.cloud-platform.service.justice.gov.uk/ + description: Staging API +- url: https://hmpps-book-secure-move-api-uat.apps.cloud-platform.service.justice.gov.uk/ + description: UAT API +- url: https://hmpps-book-secure-move-api-preprod.apps.cloud-platform.service.justice.gov.uk/a + description: PreProd API +- url: https://api.bookasecuremove.service.justice.gov.uk/ + description: Production API +security: +- oauth2: [] +components: + securitySchemes: + oauth2: + type: oauth2 + flows: + clientCredentials: + authorizationUrl: "/oauth/authorize" + tokenUrl: "/oauth/token/" + scopes: {} + schemas: + Category: + "$ref": "../v2/category.yaml#/Category" +paths: + "/subject-access-request": + get: + summary: Returns all information related to the specified PRN + tags: + - SubjectAccessRequest + consumes: + - application/vnd.api+json + parameters: + - "$ref": "../v2/accept_type_parameter.yaml#/Accept" + - "$ref": "../v1/content_type_parameter.yaml#/ContentType" + - "$ref": "../v2/accept_encoding.yaml#/AcceptEncoding" + - name: pnr + in: query + description: Filters results to only include people identified by their police_national_computer. + This is a case insensitive search. Either filter[police_national_computer], + filter[prison_number] or filter[criminal_records_office] are supported. + schema: + type: string + example: 07/1435713R + format: string + required: false + responses: + '200': + description: success + content: + application/vnd.api+json: + schema: + "$ref": "../v2/get_subject_access_request_responses.yaml#/200" + '204': + description: no content + content: + application/vnd.api+json: + schema: + "$ref": "../v2/get_subject_access_request_responses.yaml#/204" + '209': + description: unsuppoted parameter + content: + application/vnd.api+json: + schema: + "$ref": "../v2/get_subject_access_request_responses.yaml#/209" + '400': + description: bad request + content: + application/vnd.api+json: + schema: + "$ref": "../v2/get_subject_access_request_responses.yaml#/400" + '401': + description: unauthorized + content: + application/vnd.api+json: + schema: + "$ref": "../v2/get_subject_access_request_responses.yaml#/401" + '403': + description: forbidden + content: + application/vnd.api+json: + schema: + "$ref": "../v2/get_subject_access_request_responses.yaml#/403" diff --git a/swagger/v2/get_subject_access_request_responses.yaml b/swagger/v2/get_subject_access_request_responses.yaml index 78975b7c0..8599a0dbc 100644 --- a/swagger/v2/get_subject_access_request_responses.yaml +++ b/swagger/v2/get_subject_access_request_responses.yaml @@ -12,4 +12,36 @@ errors: type: array items: - $ref: errors.yaml#/BadRequest + $ref: "../v1/errors.yaml#/BadRequest" +'401': + type: object + required: + - errors + properties: + errors: + type: array + items: + type: object + properties: + title: + type: string + example: Not authorized + detail: + type: string + example: Valid authorisation token required +'403': + type: object + required: + - errors + properties: + errors: + type: array + items: + type: object + properties: + title: + type: string + example: Forbidden + detail: + type: string + example: "Missing role: ROLE_SAR_DATA_ACCESS"