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

[Daniel Axtens]

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...

> +        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 at lists.ozlabs.org
> https://lists.ozlabs.org/listinfo/patchwork