Add tags to swagger specification #230

svdwoude · 2018-01-21T17:26:04Z

Adding functionality to parse tags from plumber annotation and add to swagger-json.

Example:

#* @apiTitle Tags Example
#* @apiTag name1 description1
#* @apiTag name2 description2
#* @apiTag name3_with_whitespaces description2


#* Example endpoint with one tag
#* @tag name1
#* @get /f1
function() {

}

#* Example endpoint with multiple tags
#* @tag name1
#* @tag name2
#* @get /f2
function() {}

#* Example endpoint with unmatched tags
#* @tag randomName
#* @get /f3
function() {}

#* Example endpoint with tag with whitespaces
#* @tag name3_with_whitespaces
#* @get /f4
function() {}

Which would create a swagger-ui with 4 tags:

name1
- /f1
- /f2
name2
- /f2
randomName
- /f3
name3 with whitepsace
- /f4

Screenshot below:

CLAassistant · 2018-01-21T17:26:10Z

All committers have signed the CLA.

codecov-io · 2018-01-21T17:31:09Z

Codecov Report

Merging #230 into master will increase coverage by <.01%.
The diff coverage is 86.2%.

@@            Coverage Diff             @@
##           master     #230      +/-   ##
==========================================
+ Coverage   88.18%   88.18%   +<.01%     
==========================================
  Files          24       24              
  Lines        1193     1219      +26     
==========================================
+ Hits         1052     1075      +23     
- Misses        141      144       +3

Impacted Files	Coverage Δ
R/swagger.R	`71.92% <0%> (-1.29%)`	⬇️
R/parse-globals.R	`100% <100%> (ø)`	⬆️
R/plumber-step.R	`82.14% <66.66%> (-0.58%)`	⬇️
R/parse-block.R	`96.48% <93.33%> (-0.3%)`	⬇️

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 65af6a9...1864670. Read the comment docs.

trestletech

Looking good! Just a couple of things to revisit.

trestletech · 2018-01-22T21:23:05Z

R/parse-block.R

@@ -179,6 +180,18 @@ parseBlock <- function(lineNum, file){
      params[[name]] <- list(desc=paramMat[1,5], type=type, required=reqd)
    }

+    tagMat <- stringi::stri_match(line, regex="^#['\\*]\\s*@tag\\s+(\\S.+)\\s*")
+    if (!is.na(tagMat[1,1])){
+      t <- gsub("_"," ",stri_trim_both(tagMat[1,2]))


The underscore-to-space translation feels like a little too much magic to me. I think I'd prefer to just not handle whitespace for now and if people start asking for it then deal with it then.

Fair enough. Updated in 8beafad

trestletech · 2018-01-22T21:25:04Z

R/parse-globals.R

+         },
+         apiTag={
+           tagMat <- stringi::stri_match(def, regex="^\\s*(\\w+)\\s+(\\S.+)\\s*$")
+           name <- gsub("_"," ",tagMat[1,2])


Same as above

Fair enough. Updated in 8beafad

trestletech · 2018-01-22T21:26:50Z

R/plumber-step.R

@@ -133,6 +134,9 @@ PlumberEndpoint <- R6Class(
      if (!missing(responses)){
        self$responses <- responses
      }
+      if(!missing(tags) && !is.null(tags)){
+        self$tags <- I(tags)


Can you help me understand the I() call here?

If we only have one tag, we want to make sure it's boxed in.
In JSON we want tags: ["tagName"] instead of tags: "tagName"

Would be great to have a comment inline for that so I don't lose track of it in the future, but that makes sense.

trestletech · 2018-01-22T21:28:31Z

tests/testthat/test-globals.R

@@ -28,7 +28,8 @@ test_that("parseGlobals works", {
             "#' @apiBasePath basepath",
             "#' @apiSchemes schemes",
             "#' @apiConsumes consumes",
-             "#' @apiProduces produces")
+             "#' @apiProduces produces",
+             "#' @apiTag tag description")


Can we add multiple tag definitions here for this test? And perhaps also a test that has redundant apiTag definitions? I'd think that should fail but I don't believe that it does today.

Multiple tags added in test.
I've also added a test to check for redundant apiTag definitions (= duplicates). Since swagger is pretty relaxed about unused tag definitions, I did not add a test to see wether all apiTag definitions are also referenced in at least one endpoint.

trestletech · 2018-01-22T21:29:08Z

R/parse-globals.R

+           tagMat <- stringi::stri_match(def, regex="^\\s*(\\w+)\\s+(\\S.+)\\s*$")
+           name <- gsub("_"," ",tagMat[1,2])
+           description <- tagMat[1,3]
+           fields$tags <- rbind(fields$tags,data.frame(name=name,description=description))


should we do a stringsAsFactors = FALSE here? I usually prefer it.

Good idea. Added in 1f509a0

jeffkeller87 · 2018-01-23T21:13:55Z

Really excited to see more code decoration support!

trestletech · 2018-01-23T21:41:28Z

I saw the commits come in; let me know when this is ready for rereview and I'll take another pass!

svdwoude · 2018-01-23T21:43:06Z

Ready for review!

trestletech · 2018-01-23T22:03:14Z

Looks great! I pushed one more commit for some doc updates and to add you to the DESCRIPTION file. I pulled the email from your public GitHub profile, but let me know if you'd prefer to be removed or use a different address.

If that looks good, I'll go ahead and pull it in once tests pass!

svdwoude · 2018-01-23T22:09:00Z

Sorry about squeezing in that last typo fix.
Probably better to use the email I did my commits with.
Changed that meanwhile on my profile.

Thanks for checking with me ☺️

trestletech · 2018-01-23T22:36:50Z

🎉

Thanks again for you contribution!

svdwoude added 9 commits January 14, 2018 14:34

parse @tag from endpoint and store as vector

4f285fd

add tags list item to plumberEndpoint

60a6137

parse and add tag definition

8706eda

don't add empty tag property by default

cddf88b

tags of endpoints with one tag should be boxed during JSON conversion

1ea8db5

convert underscores to spaces to allow for tag-names with whitespaces

e1c1f42

throw error on empty and duplicate tag

5c0e869

test for duplicate tags

8e0c08a

include @apiTag to "parseGlobals works" test

8b11284

trestletech suggested changes Jan 23, 2018

View reviewed changes

svdwoude added 4 commits January 23, 2018 20:03

underscore-to-space translation feels like a little too much magic

8beafad

added stringsAsFactors=FALSE

1f509a0

multiple tag definitions for tests

a7a6143

test for redundant tag definitions

83be054

svdwoude and others added 2 commits January 23, 2018 22:46

adding comments

26f4440

Update DESCRIPTION, NEWS, and swagger example

f481fc9

trestletech approved these changes Jan 23, 2018

View reviewed changes

fix comment typo

a7032c1

updating email

1864670

trestletech merged commit f98b41b into rstudio:master Jan 23, 2018

trestletech mentioned this pull request Jan 23, 2018

Add tags to swagger specification #226

Closed

jeffkeller87 mentioned this pull request Nov 20, 2018

[Feature Request] Allow spaces in @apiTag #350

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add tags to swagger specification #230

Add tags to swagger specification #230

svdwoude commented Jan 21, 2018

CLAassistant commented Jan 21, 2018 •

edited

Loading

codecov-io commented Jan 21, 2018 •

edited

Loading

trestletech left a comment

trestletech Jan 22, 2018

svdwoude Jan 23, 2018

trestletech Jan 22, 2018

svdwoude Jan 23, 2018

trestletech Jan 22, 2018

svdwoude Jan 23, 2018

trestletech Jan 23, 2018

trestletech Jan 22, 2018

svdwoude Jan 23, 2018

trestletech Jan 22, 2018

svdwoude Jan 23, 2018

jeffkeller87 commented Jan 23, 2018

trestletech commented Jan 23, 2018

svdwoude commented Jan 23, 2018

trestletech commented Jan 23, 2018

svdwoude commented Jan 23, 2018 •

edited

Loading

trestletech commented Jan 23, 2018

Add tags to swagger specification #230

Add tags to swagger specification #230

Conversation

svdwoude commented Jan 21, 2018

CLAassistant commented Jan 21, 2018 • edited Loading

codecov-io commented Jan 21, 2018 • edited Loading

Codecov Report

trestletech left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jeffkeller87 commented Jan 23, 2018

trestletech commented Jan 23, 2018

svdwoude commented Jan 23, 2018

trestletech commented Jan 23, 2018

svdwoude commented Jan 23, 2018 • edited Loading

trestletech commented Jan 23, 2018

CLAassistant commented Jan 21, 2018 •

edited

Loading

codecov-io commented Jan 21, 2018 •

edited

Loading

svdwoude commented Jan 23, 2018 •

edited

Loading