On Fri, 2018-11-09 at 00:22 +1100, Daniel Axtens wrote: > Stephen Finucane <[email protected]> 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 <[email protected]> > > --- > > 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: [email protected] > > + 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 > > [email protected] > > https://lists.ozlabs.org/listinfo/patchwork _______________________________________________ Patchwork mailing list [email protected] https://lists.ozlabs.org/listinfo/patchwork
