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
CMSgov · Dec 4, 2018 · a3147ab · a3147ab
1 parent d0c41ed
commit a3147ab
Show file tree

Hide file tree

Showing 3 changed files with 14 additions and 13 deletions.
diff --git 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: [email protected]
@@ -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 <UUID>.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
@@ -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
@@ -3,7 +3,7 @@
 <html lang="en">
   <head>
     <meta charset="UTF-8">
-    <title>Swagger UI</title>
+    <title>BCDA Documentation</title>
     <link rel="stylesheet" type="text/css" href="./swagger-ui.css" >
     <link rel="icon" type="image/png" href="./favicon-32x32.png" sizes="32x32" />
     <link rel="icon" type="image/png" href="./favicon-16x16.png" sizes="16x16" />