From a3147ab196982d6792e6296564405fae6a2e49e5 Mon Sep 17 00:00:00 2001 From: Michael Knoll <42681520+knollfear@users.noreply.github.com> Date: Mon, 3 Dec 2018 21:49:36 -0500 Subject: [PATCH] knollfear/bcda-553 Swagger doc improvements (#86) * Minor changes to swagger docs to make it clear how to use the authorize function and make exploring the API a little easier. * changed document title to BCDA documentation instead of swagger ui --- bcda/api.go | 20 +++++++++----------- bcda/models/SwaggerStructs.go | 5 ++++- bcda/swaggerui/index.html | 2 +- 3 files changed, 14 insertions(+), 13 deletions(-) diff --git a/bcda/api.go b/bcda/api.go index dc2ce9a4c..a70be76de 100644 --- a/bcda/api.go +++ b/bcda/api.go @@ -3,13 +3,11 @@ The Beneficiary Claims Data API (BCDA) allows downloading of claims data in accordance with the FHIR Bulk Data Export specification. - Terms Of Service: + If you have a token you can use this page to explore the API. To do this click the green "Authorize" button below and enter "Bearer {YOUR_TOKEN}" + in the "Value" field and click authorize. Until you click logout your token will be presented with every request made. To make requests click on the + "Try it out" button for the desired endpoint. - there are no TOS at this moment, use at your own risk we take no responsibility - Schemes: http, https - Host: localhost - BasePath: /api/v1 Version: 1.0.0 License: https://github.com/CMSgov/bcda-app/blob/master/LICENSE.md Contact: bcapi@cms.hhs.gov @@ -57,7 +55,7 @@ import ( ) /* - swagger:route GET /ExplanationOfBenefit/$export bulkData bulkRequest + swagger:route GET /api/v1/ExplanationOfBenefit/$export bulkData bulkRequest Start explanation of benefit export @@ -66,7 +64,7 @@ import ( Produces: - application/fhir+json - Schemes: http, https + Schemes: [http, https] Security: api_key @@ -183,7 +181,7 @@ func bulkRequest(w http.ResponseWriter, r *http.Request) { } /* - swagger:route GET /jobs/{jobId} bulkData jobStatus + swagger:route GET /api/v1/jobs/{jobId} bulkData jobStatus Get job status @@ -308,11 +306,11 @@ func jobStatus(w http.ResponseWriter, r *http.Request) { } /* - swagger:route GET /data/{jobId}/{filename}.ndjson bulkData serveData + swagger:route GET /data/{jobId}/{filename} bulkData serveData Get data file - Returns the NDJSON file of data generated by an export job. + Returns the NDJSON file of data generated by an export job. Will be in the format .ndjson. Get the full value from the job status response Produces: - application/fhir+json @@ -413,7 +411,7 @@ func blueButtonMetadata(w http.ResponseWriter, r *http.Request) { } /* - swagger:route GET /metadata metadata metadata + swagger:route GET /api/v1/metadata metadata metadata Get metadata diff --git a/bcda/models/SwaggerStructs.go b/bcda/models/SwaggerStructs.go index 3e49d775d..dac0d1d0d 100644 --- a/bcda/models/SwaggerStructs.go +++ b/bcda/models/SwaggerStructs.go @@ -106,9 +106,12 @@ type FileParam struct { // swagger:parameters bulkRequest type BulkRequestHeaders struct { // required: true - // pattern: application/fhir\+json + // in: header + // enum: [application/fhir+json] Accept string // required: true // pattern: respond-async + // in: header + // enum: [respond-async] Prefer string } diff --git a/bcda/swaggerui/index.html b/bcda/swaggerui/index.html index 623852440..4e1294fef 100755 --- a/bcda/swaggerui/index.html +++ b/bcda/swaggerui/index.html @@ -3,7 +3,7 @@ - Swagger UI + BCDA Documentation