[05/17] docs: Start documenting API using OpenAPI

Message ID 20181030111916.7342-6-stephen@that.guru
State New
Headers show
Series
  • Add OpenAPI 3.0.0 REST API spec
Related show

Commit Message

Stephen Finucane Oct. 30, 2018, 11:19 a.m.
When the REST API was first added, we attempted to document it using
OpenAPI 2.0 (formerly Swagger). This was mostly never completed because
(a) it was really tedious and (b) no one was that bothered. However, as
we expand the range of clients for the REST API, having a well
documented API becomes more and more of an asset.

Start doing this by adding a brand new schema, this time using OpenAPI.
This will entirely replace the older schema and, as such, is namespaced
separately. We start by documenting '/' (i.e. the index) page and will
add additional resources as we go.

Signed-off-by: Stephen Finucane <stephen@that.guru>
---
 docs/api/schemas/patchwork.yaml | 76 +++++++++++++++++++++++++++++++++
 1 file changed, 76 insertions(+)
 create mode 100644 docs/api/schemas/patchwork.yaml

Comments

Daniel Axtens Nov. 8, 2018, 1:22 p.m. | #1
Stephen Finucane <stephen@that.guru> writes:

> When the REST API was first added, we attempted to document it using
> OpenAPI 2.0 (formerly Swagger). This was mostly never completed because
> (a) it was really tedious and (b) no one was that bothered. However, as
> we expand the range of clients for the REST API, having a well
> documented API becomes more and more of an asset.
>
> Start doing this by adding a brand new schema, this time using OpenAPI.
> This will entirely replace the older schema and, as such, is namespaced
> separately. We start by documenting '/' (i.e. the index) page and will
> add additional resources as we go.
>
> Signed-off-by: Stephen Finucane <stephen@that.guru>
> ---
>  docs/api/schemas/patchwork.yaml | 76 +++++++++++++++++++++++++++++++++
>  1 file changed, 76 insertions(+)
>  create mode 100644 docs/api/schemas/patchwork.yaml
>
> diff --git a/docs/api/schemas/patchwork.yaml b/docs/api/schemas/patchwork.yaml
> new file mode 100644
> index 00000000..804d0c3f
> --- /dev/null
> +++ b/docs/api/schemas/patchwork.yaml
> @@ -0,0 +1,76 @@
> +openapi: '3.0.0'
> +info:
> +  title: Patchwork API
> +  description: |
> +    Patchwork is a web-based patch tracking system designed to facilitate the
> +    contribution and management of contributions to an open-source project.
> +  contact:
> +    email: patchwork@lists.ozlabs.org
> +  license:
> +    name: GPL v2 License
> +    url: https://www.gnu.org/licenses/gpl-2.0.html
> +  version: '1.1'
> +paths:
> +  /api/:
> +    get:
> +      description: List API resources.
> +      operationId: api_list
> +      parameters: []
> +      responses:
> +        '200':
> +          description: ''
> +          content:
> +            application/json:
> +              schema:
> +                $ref: '#/components/schemas/Index'
> +      tags:
> +      - api
> +components:
> +  securitySchemes:
> +    basicAuth:
> +      type: http
> +      scheme: basic
> +    apiKeyAuth:
> +      type: http
> +      scheme: bearer
> +  schemas:
> +    Index:
> +      type: object
> +      properties:
> +        bundles:
> +          title: Bundles URL
I'm guessing this was largely auto-generated, because having to type
> +          type: string
> +          format: uri
> +          readOnly: true
over and over seems really tedious...

> +        covers:
> +          title: Covers URL
> +          type: string
> +          format: uri
> +          readOnly: true
> +        events:
> +          title: Events URL
> +          type: string
> +          format: uri
> +          readOnly: true
> +        patches:
> +          title: Patches URL
> +          type: string
> +          format: uri
> +          readOnly: true
> +        people:
> +          title: People URL
> +          type: string
> +          format: uri
> +          readOnly: true
> +        projects:
> +          title: Projects URL
> +          type: string
> +          format: uri
> +          readOnly: true
> +        users:
> +          title: Users URL
> +          type: string
> +          format: uri
> +          readOnly: true
> +servers:
> +- url: 'https://patchwork.ozlabs.org/api/1.1'

What does the servers mapping signify? I just worry a bit about making
OzLabs the canonical reference point as it isn't always up to date...

Regards,
Daniel

> -- 
> 2.17.2
>
> _______________________________________________
> Patchwork mailing list
> Patchwork@lists.ozlabs.org
> https://lists.ozlabs.org/listinfo/patchwork
Stephen Finucane Nov. 8, 2018, 2:09 p.m. | #2
On Fri, 2018-11-09 at 00:22 +1100, Daniel Axtens wrote:
> Stephen Finucane <stephen@that.guru> writes:
> 
> > When the REST API was first added, we attempted to document it using
> > OpenAPI 2.0 (formerly Swagger). This was mostly never completed because
> > (a) it was really tedious and (b) no one was that bothered. However, as
> > we expand the range of clients for the REST API, having a well
> > documented API becomes more and more of an asset.
> > 
> > Start doing this by adding a brand new schema, this time using OpenAPI.
> > This will entirely replace the older schema and, as such, is namespaced
> > separately. We start by documenting '/' (i.e. the index) page and will
> > add additional resources as we go.
> > 
> > Signed-off-by: Stephen Finucane <stephen@that.guru>
> > ---
> >  docs/api/schemas/patchwork.yaml | 76 +++++++++++++++++++++++++++++++++
> >  1 file changed, 76 insertions(+)
> >  create mode 100644 docs/api/schemas/patchwork.yaml
> > 
> > diff --git a/docs/api/schemas/patchwork.yaml b/docs/api/schemas/patchwork.yaml
> > new file mode 100644
> > index 00000000..804d0c3f
> > --- /dev/null
> > +++ b/docs/api/schemas/patchwork.yaml
> > @@ -0,0 +1,76 @@
> > +openapi: '3.0.0'
> > +info:
> > +  title: Patchwork API
> > +  description: |
> > +    Patchwork is a web-based patch tracking system designed to facilitate the
> > +    contribution and management of contributions to an open-source project.
> > +  contact:
> > +    email: patchwork@lists.ozlabs.org
> > +  license:
> > +    name: GPL v2 License
> > +    url: https://www.gnu.org/licenses/gpl-2.0.html
> > +  version: '1.1'
> > +paths:
> > +  /api/:
> > +    get:
> > +      description: List API resources.
> > +      operationId: api_list
> > +      parameters: []
> > +      responses:
> > +        '200':
> > +          description: ''
> > +          content:
> > +            application/json:
> > +              schema:
> > +                $ref: '#/components/schemas/Index'
> > +      tags:
> > +      - api
> > +components:
> > +  securitySchemes:
> > +    basicAuth:
> > +      type: http
> > +      scheme: basic
> > +    apiKeyAuth:
> > +      type: http
> > +      scheme: bearer
> > +  schemas:
> > +    Index:
> > +      type: object
> > +      properties:
> > +        bundles:
> > +          title: Bundles URL
> I'm guessing this was largely auto-generated, because having to type
> > +          type: string
> > +          format: uri
> > +          readOnly: true
> over and over seems really tedious...

You're telling me :) Yeah, this was initially auto-generated with a
combination of drf-yasg and DRF's new 'generateschema' command, the
former of which produced a pretty good schema but in openapi 2.0 format
and the latter of which produced an mostly useless schema but in
openapi 3.0.0 format. I imagine this will be easier to extend going
forward than it was to write from scratch.

> > +        covers:
> > +          title: Covers URL
> > +          type: string
> > +          format: uri
> > +          readOnly: true
> > +        events:
> > +          title: Events URL
> > +          type: string
> > +          format: uri
> > +          readOnly: true
> > +        patches:
> > +          title: Patches URL
> > +          type: string
> > +          format: uri
> > +          readOnly: true
> > +        people:
> > +          title: People URL
> > +          type: string
> > +          format: uri
> > +          readOnly: true
> > +        projects:
> > +          title: Projects URL
> > +          type: string
> > +          format: uri
> > +          readOnly: true
> > +        users:
> > +          title: Users URL
> > +          type: string
> > +          format: uri
> > +          readOnly: true
> > +servers:
> > +- url: 'https://patchwork.ozlabs.org/api/1.1'
> 
> What does the servers mapping signify? I just worry a bit about making
> OzLabs the canonical reference point as it isn't always up to date...

This field is really intended for deployed applications as opposed to
installable ones, I guess, and unfortunately we don't have anything
better to use as a canonical reference point. I can see if I can drop
it at merge time but, assuming it's not possible to do so, this won't
actually be used in our documentation and can probable be ignored?

Stephen

> Regards,
> Daniel
> 
> > -- 
> > 2.17.2
> > 
> > _______________________________________________
> > Patchwork mailing list
> > Patchwork@lists.ozlabs.org
> > https://lists.ozlabs.org/listinfo/patchwork

Patch

diff --git a/docs/api/schemas/patchwork.yaml b/docs/api/schemas/patchwork.yaml
new file mode 100644
index 00000000..804d0c3f
--- /dev/null
+++ b/docs/api/schemas/patchwork.yaml
@@ -0,0 +1,76 @@ 
+openapi: '3.0.0'
+info:
+  title: Patchwork API
+  description: |
+    Patchwork is a web-based patch tracking system designed to facilitate the
+    contribution and management of contributions to an open-source project.
+  contact:
+    email: patchwork@lists.ozlabs.org
+  license:
+    name: GPL v2 License
+    url: https://www.gnu.org/licenses/gpl-2.0.html
+  version: '1.1'
+paths:
+  /api/:
+    get:
+      description: List API resources.
+      operationId: api_list
+      parameters: []
+      responses:
+        '200':
+          description: ''
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Index'
+      tags:
+      - api
+components:
+  securitySchemes:
+    basicAuth:
+      type: http
+      scheme: basic
+    apiKeyAuth:
+      type: http
+      scheme: bearer
+  schemas:
+    Index:
+      type: object
+      properties:
+        bundles:
+          title: Bundles URL
+          type: string
+          format: uri
+          readOnly: true
+        covers:
+          title: Covers URL
+          type: string
+          format: uri
+          readOnly: true
+        events:
+          title: Events URL
+          type: string
+          format: uri
+          readOnly: true
+        patches:
+          title: Patches URL
+          type: string
+          format: uri
+          readOnly: true
+        people:
+          title: People URL
+          type: string
+          format: uri
+          readOnly: true
+        projects:
+          title: Projects URL
+          type: string
+          format: uri
+          readOnly: true
+        users:
+          title: Users URL
+          type: string
+          format: uri
+          readOnly: true
+servers:
+- url: 'https://patchwork.ozlabs.org/api/1.1'