Mholloway has uploaded a new change for review.

  https://gerrit.wikimedia.org/r/315995

Change subject: Add response definitions to spec for feed endpoints
......................................................................

Add response definitions to spec for feed endpoints

Additional schema checks using these will be added in the next patch in
this series (note that the existing checks only validate the spec examples
and these additional checks will give us more flexibility, e.g., to check
that failing requests, for which we don't necessarily want to create
examples, fail in the right way).

Also added some blank lines for readability.

Bug: T145075
Change-Id: I6331a18f4b13ff7864ec73c969fd86d3e9ce732c
---
M spec.yaml
1 file changed, 202 insertions(+), 0 deletions(-)


  git pull ssh://gerrit.wikimedia.org:29418/mediawiki/services/mobileapps 
refs/changes/95/315995/1

diff --git a/spec.yaml b/spec.yaml
index c3acd69..aa9ef92 100644
--- a/spec.yaml
+++ b/spec.yaml
@@ -1,4 +1,5 @@
 swagger: '2.0'
+
 info:
   version: 0.1.0
   title: WMF MobileApps service
@@ -10,8 +11,10 @@
   license:
     name: Apache2
     url: http://www.apache.org/licenses/LICENSE-2.0
+
 x-default-params:
   domain: en.wikipedia.org
+
 paths:
   # from routes/root.js
   /robots.txt:
@@ -21,6 +24,7 @@
         - Robots
       description: Gets robots.txt
       x-monitor: false
+
   /:
     get:
       tags:
@@ -35,6 +39,7 @@
               spec: true
           response:
             status: 200
+
   # from routes/info.js
   /_info:
     get:
@@ -55,6 +60,7 @@
               description: /.+/
               version: /.+/
               home: /.+/
+
   # from routes/featured.js
   /{domain}/v1/page/featured/{yyyy}/{mm}/{dd}:
     get:
@@ -85,6 +91,17 @@
           required: true
           minimum: "01"
           maximum: "31"
+      responses:
+        '200':
+          description: The title of a Wikipedia's Featured Article of the Day
+          schema:
+            $ref: '#/definitions/article_title'
+        '204':
+          description: Empty response (for feed content aggregation requests 
from RESTBase)
+        default:
+          description: Error
+          schema:
+            $ref: '#/definitions/problem'
       x-amples:
         - title: retrieve title of the featured article for April 29, 2016
           request:
@@ -110,6 +127,7 @@
           response:
             status: 204
             body: ""
+
   # from routes/featured-image.js
   /{domain}/v1/media/image/featured/{yyyy}/{mm}/{dd}:
     get:
@@ -140,6 +158,17 @@
           required: true
           minimum: "01"
           maximum: "31"
+      responses:
+        '200':
+          description: Info on the Commons Featured Image of the Day for the 
requested date
+          schema:
+            $ref: '#/definitions/image'
+        '204':
+          description: Empty response (for feed content aggregation requests 
from RESTBase)
+        default:
+          description: Error
+          schema:
+            $ref: '#/definitions/problem'
       x-amples:
         - title: retrieve featured image data for April 29, 2016
           request:
@@ -164,6 +193,7 @@
                 source: /.+/
                 width: /.+/
                 height: /.+/
+
   # from routes/most-read.js
   /{domain}/v1/page/most-read/{yyyy}/{mm}/{dd}:
     get:
@@ -194,6 +224,17 @@
           required: true
           minimum: "01"
           maximum: "31"
+      responses:
+        '200':
+          description: Most-read article titles for this wiki for the 
requested date
+          schema:
+            $ref: '#/definitions/mostread'
+        '204':
+          description: Empty response (for feed content aggregation requests 
from RESTBase)
+        default:
+          description: Error
+          schema:
+            $ref: '#/definitions/problem'
       x-amples:
         - title: retrieve the most-read articles for January 1, 2016
           request:
@@ -240,6 +281,7 @@
           response:
             status: 204
             body: ""
+
   # from routes/random.js
   /{domain}/v1/page/random/title:
     get:
@@ -248,6 +290,15 @@
       description: Gets the title of a randomly picked article from main 
namespace. Preference is given to articles with a thumbnail, long extract, and 
an associated Wikidata description.
       produces:
         - application/json
+      responses:
+        '200':
+          description: A random (good) article title
+          schema:
+            $ref: '#/definitions/random'
+        default:
+          description: Error
+          schema:
+            $ref: '#/definitions/problem'
       x-amples:
         - title: retrieve a random article
           response:
@@ -257,6 +308,7 @@
             body:
               items:
                 - title: /.+/
+
   # from routes/news.js
   /{domain}/v1/page/news:
     get:
@@ -265,6 +317,17 @@
       description: Gets content related to the current In the News template 
(experimental, English-only).
       produces:
         - application/json
+      responses:
+        '200':
+          description: News content from the a Wikipedia main page
+          schema:
+            $ref: '#/definitions/news'
+        '204':
+          description: Empty response (for feed content aggregation requests 
from RESTBase)
+        default:
+          description: Error
+          schema:
+            $ref: '#/definitions/problem'
       x-amples:
         - title: get 'In the News' content
           response:
@@ -284,6 +347,7 @@
           response:
             status: 204
             body: ""
+
   # from routes/media.js
   /{domain}/v1/page/media/{title}:
     get:
@@ -307,6 +371,7 @@
                   url: /.+/
                   width: /.+/
                   height: /.+/
+
   # from routes/definition.js
   /{domain}/v1/page/definition/{title}:
     get:
@@ -326,6 +391,7 @@
             headers:
               content-type: application/json
             body: /.+/
+
   # from routes/mobile-sections.js
   /{domain}/v1/page/mobile-sections/{title}:
     get:
@@ -360,6 +426,7 @@
                 sections: [ /.+/ ]
               remaining:
                 sections: []
+
   /{domain}/v1/page/mobile-sections-lead/{title}:
     get:
       tags:
@@ -396,6 +463,7 @@
                 latitude: /.+/
                 longitude: /.+/
               sections: [ /.+/ ]
+
   /{domain}/v1/page/mobile-sections-remaining/{title}:
     get:
       tags:
@@ -404,6 +472,7 @@
       produces:
         - application/json
       x-monitor: false
+
   # from routes/mobile-summary.js
   /{domain}/v1/page/mobile-summary/{title}:
     get:
@@ -427,6 +496,7 @@
               thumbnail:
                 source: /.+/
               infobox: [ /.+/ ]
+
   # from routes/mobile-text.js
   /{domain}/v1/page/mobile-text/{title}:
     get:
@@ -436,3 +506,135 @@
       produces:
         - application/json
       x-monitor: false
+
+definitions:
+  # A https://tools.ietf.org/html/draft-nottingham-http-problem
+  problem:
+    required:
+      - type
+    properties:
+      type:
+        type: string
+      title:
+        type: string
+      detail:
+        type: string
+      instance:
+        type: string
+
+  article_title:
+    type: object
+    properties:
+      title:
+        type: string
+        description: An article title
+    required:
+      - title
+
+  thumbnail:
+    type: object
+    properties:
+      source:
+        type: string
+        description: Thumbnail image URI
+      width:
+        type: integer
+        description: Thumbnail width
+      height:
+        type: integer
+        description: Thumnail height
+    required: ['source', 'width', 'height']
+
+  mostread_article:
+    type: object
+    properties:
+      title:
+        type: string
+        description: Article title in a form of DB key
+      views:
+        type: integer
+        description: Number of views on the requested day
+      rank:
+        type: integer
+        description: Position in the list of most viewed articles
+    required:
+      - title
+      - views
+      - rank
+
+  mostread:
+    type: object
+    properties:
+      date:
+        type: string
+        description: The date which the data correspond to
+      articles:
+        type: array
+        description: Array of most popular articles
+        items:
+          $ref: '#/definitions/mostread_article'
+    required:
+      - date
+      - articles
+
+  news_item:
+    type: object
+    properties:
+      story:
+        type: string
+        description: A cover story for the news item
+      links:
+        type: array
+        description: A collection of articles related to the news item
+        items:
+          $ref: '#/definitions/article_title'
+    required:
+      - story
+      - links
+
+  news:
+    type: array
+    items:
+      $ref: '#/definitions/news_item'
+
+  random:
+    type: object
+    properties:
+      items:
+        type: array
+        items:
+          $ref: '#/definitions/article_title'
+    required:
+      - items
+
+  image_description:
+    properties:
+      text:
+        type: string
+        description: Text of the description
+      lang:
+        type: string
+        description: Language code of the description
+    required:
+      - text
+      - lang
+
+  image:
+    type: object
+    properties:
+      title:
+        type: string
+        description: Image title
+      thumbnail:
+        description: Image thumbnail
+        $ref: '#/definitions/thumbnail'
+      image:
+        description: Full-size image
+        $ref: '#/definitions/thumbnail'
+      description:
+        descrtiption: Description of an image
+        $ref: '#/definitions/image_description'
+    required:
+      - title
+      - thumbnail
+      - image

-- 
To view, visit https://gerrit.wikimedia.org/r/315995
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings

Gerrit-MessageType: newchange
Gerrit-Change-Id: I6331a18f4b13ff7864ec73c969fd86d3e9ce732c
Gerrit-PatchSet: 1
Gerrit-Project: mediawiki/services/mobileapps
Gerrit-Branch: master
Gerrit-Owner: Mholloway <mhollo...@wikimedia.org>

_______________________________________________
MediaWiki-commits mailing list
MediaWiki-commits@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits

Reply via email to