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

[Stephen Finucane]

On Fri, 2018-11-09 at 00:22 +1100, Daniel Axtens wrote:
> Stephen Finucane <stephen at 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 at 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 at 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 at lists.ozlabs.org
> > https://lists.ozlabs.org/listinfo/patchwork