| Message ID | 20181030111916.7342-6-stephen@that.guru |
|---|---|
| State | Accepted |
| Headers | show |
| Series | Add OpenAPI 3.0.0 REST API spec | expand |
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
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
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'
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