rust codegen

This re-ordered a lot of code, because several endpoints had their tags
changed, but should be no actual change in behavior/spec.

1 files changed, 983 insertions, 85 deletions

diff --git a/rust/fatcat-openapi/api.yaml b/rust/fatcat-openapi/api.yaml
index 95ef4c6b..3de72126 100644
--- a/rust/fatcat-openapi/api.yaml
+++ b/rust/fatcat-openapi/api.yaml
@@ -2,9 +2,86 @@
 swagger: "2.0"
 info:
   title: fatcat
-  description: A scalable, versioned, API-oriented catalog of bibliographic entities
-    and file metadata
   version: 0.3.0
+  description: |
+    Fatcat is a scalable, versioned, API-oriented catalog of bibliographic
+    entities and file metadata.
+
+    <!-- STARTLONGDESCRIPTION -->
+    These API reference documents, along with client software libraries, are
+    generated automatically from an OpenAPI 2.0 ("Swagger") definition file.
+
+    ## Introduction
+
+
+    A higher-level introduction to the API, as well as a description of the
+    fatcat data model, are available in ["The Fatcat Guide"](https://guide.fatcat.wiki/).
+    The guide also includes a [Cookbook](https://guide.fatcat.wiki/cookbook.html)
+    section demonstrating end-to-end tasks like creating entities as part of
+    editgroups, or safely merging duplicate entities.
+
+    ### Expectations and Best Practices
+
+    A test/staging QA API instance of fatcat is available at
+    <https://api.qa.fatcat.wiki/v0>. The database backing this instance is
+    separate from the production interface, and is periodically rebuilt from
+    snapshots of the full production database, meaning that edits on the QA
+    server will *NOT* persist, and that semantics like the changelog index
+    monotonically increasing *MAY* be broken. Developers are expexcted to test
+    their scripts and tools against the QA instance before running against
+    production.
+
+    Fatcat is made available as a gratis (no cost) and libre (freedom
+    preserving) service to the public, with limited funding and resources. We
+    welcome new and unforseen uses and contributions, but may need to impose
+    restrictions (like rate-limits) to keep the service functional for other
+    users, and in extreme cases reserve the option to block accounts and IP
+    ranges if necessary to keep the service operational.
+
+    The Internet Archive owns and operates it's own server equipment and data
+    centers, and operations are optimized for low-cost, not high-availability.
+    Users and partners should expect some downtime on the fatcat API, on the
+    order of hours a month.
+
+    Periodic metadata exports are available for batch processing, and database
+    snapshots can be used to create locally-hosted mirrors of the service for
+    more intensive and reliable querying.
+
+    ### Other Nitty Gritties
+
+    Cross-origin requests are allowed for the API service, to enable third
+    parties to bulid in-browser applications.
+
+    A metadata search service is available at <https://search.fatcat.wiki> (and
+    <https://search.qa.fatcat.wiki>). The API is currently the raw
+    elasticsearch API, with only GET (read) requests allowed. This public
+    service is experimental and may be removed or limited in the future.
+
+    ## Authentication
+
+    The API allows basic read-only "GET" HTTP requests with no authentication.
+    Proposing changes to the metadata, or other mutating requests ("PUT",
+    "POST", "DELETE") all require authentication, and some operations require
+    additional account permissions.
+
+    End-user account creation and login happens through the web interface. From
+    a logged-in editor profile page, you can generate a API token. Tokens are
+    "macaroons", similar to JWT tokens, and are used for all API
+    authentication. The web interface includes macaroons in browser cookies and
+    passes them through to the API to authenticate editor actions.
+
+    <!-- ReDoc-Inject: <security-definitions> -->
+    <!-- ENDLONGDESCRIPTION -->
+
+  termsOfService: "https://guide.fatcat.wiki/policies.html"
+  contact:
+    name: "Internet Archive Web Group"
+    email: "webservices@archive.org"
+    url: "https://fatcat.wiki"
+  x-logo:
+    url: "https://fatcat.wiki/static/paper_man_confused.gif"
+    altText: "Confused Papers Man (Logo)"
+    backgroundColor: "#FFFFFF"
 schemes: [https]
 basePath: /v0
 host: api.fatcat.wiki
@@ -13,92 +90,252 @@ consumes:
 produces:
   - application/json
 
+x-servers:
+- url: https://api.fatcat.wiki/v0
+  description: "Production Server"
+- url: https://api.qa.fatcat.wiki/v0
+  description: "QA Server"
+
 securityDefinitions:
   Bearer:
     type: apiKey
     name: Authorization
     in: header
+    description: |
+      The only current API authentication mechanism is HTTP bearer
+      authentication using the `Authorization` HTTP header. The header should
+      be formatted as the string "Bearer", then a space, then API token (in the
+      usual base64 string encoding).
+
+      An example HTTP request would look on the wire like:
+
+          GET /v0/auth/check HTTP/1.1
+          Accept: */*
+          Accept-Encoding: gzip, deflate
+          Authorization: Bearer AgEPZGV2LmZhdGNhdC53aWtpAhYyMDE5MDEwMS1kZXYtZHVtbXkta2V5AAImZWRpdG9yX2lkID0gYWFhYWFhYWFhYWFhYmt2a2FhYWFhYWFhYWkAAht0aW1lID4gMjAxOS0wMS0wOVQwMDo1Nzo1MloAAAYgnroNha1hSftChtxHGTnLEmM/pY8MeQS/jBSV0UNvXug=
+          Connection: keep-alive
+          Host: api.qa.fatcat.wiki
+          User-Agent: HTTPie/0.9.8
+
+      Headers can be passed on the command line using `http` (HTTPie) like:
+
+          http get https://api.qa.fatcat.wiki/v0/auth/check Authorization:"Bearer AgEPZGV2LmZhdGNhdC53aWtpAhYyMDE5MDEwMS1kZXYtZHVtbXkta2V5AAImZWRpdG9yX2lkID0gYWFhYWFhYWFhYWFhYmt2a2FhYWFhYWFhYWkAAht0aW1lID4gMjAxOS0wMS0wOVQwMDo1Nzo1MloAAAYgnroNha1hSftChtxHGTnLEmM/pY8MeQS/jBSV0UNvXug="
+
+      Or with `curl`:
+
+          curl -H "Authorization: Bearer AgEPZGV2LmZhdGNhdC53aWtpAhYyMDE5MDEwMS1kZXYtZHVtbXkta2V5AAImZWRpdG9yX2lkID0gYWFhYWFhYWFhYWFhYmt2a2FhYWFhYWFhYWkAAht0aW1lID4gMjAxOS0wMS0wOVQwMDo1Nzo1MloAAAYgnroNha1hSftChtxHGTnLEmM/pY8MeQS/jBSV0UNvXug=" https://qa.fatcat.wiki/v0/auth/check
 
 tags: # TAGLINE
  - name: containers # TAGLINE
-   descriptions: "Container entities: such as journals, conferences, book series" # TAGLINE
+   x-displayName: "Containers" # TAGLINE
+   description: |  # TAGLINE
+     **Container** entities represent publication venues like journals,  # TAGLINE
+     conference proceedings, book series, or blogs. They group publications  # TAGLINE
+     ("releases").  # TAGLINE
+
+     See the "Catalog Style Guide" section of the guide for details and  # TAGLINE
+     semantics of what should be included in specific entity fields.  # TAGLINE
+     Specifically, the  # TAGLINE
+     [Container Entity Reference](https://guide.fatcat.wiki/entity_container.html).  # TAGLINE
  - name: creators # TAGLINE
-   descriptions: "Creator entities: such as authors" # TAGLINE
+   x-displayName: "Creators" # TAGLINE
+   description: |  # TAGLINE
+     **Creator** entities represent individuals (or organizations, or other  # TAGLINE
+     agents) who contribute to the creation of specific releases  # TAGLINE
+     (publications).  # TAGLINE
+
+     See the "Catalog Style Guide" section of the guide for details and  # TAGLINE
+     semantics of what should be included in specific entity fields.  # TAGLINE
+     Specifically, the  # TAGLINE
+     [Creator Entity Reference](https://guide.fatcat.wiki/entity_creator.html).  # TAGLINE
  - name: files # TAGLINE
-   descriptions: "File entities" # TAGLINE
+   x-displayName: "Files" # TAGLINE
+   description: |  # TAGLINE
+     **File** entities represent unique digital files which are full  # TAGLINE
+     manifestations of specific releases (publications), such as fulltext PDF  # TAGLINE
+     files, JATS XML documents, or video files. File entities also include a  # TAGLINE
+     set of locations where they can be found on the public web.  # TAGLINE
+
+     See the "Catalog Style Guide" section of the guide for details and  # TAGLINE
+     semantics of what should be included in specific entity fields.  # TAGLINE
+     Specifically, the  # TAGLINE
+     [File Entity Reference](https://guide.fatcat.wiki/entity_file.html).  # TAGLINE
  - name: filesets # TAGLINE
-   descriptions: "Fileset entities" # TAGLINE
+   x-displayName: "Filesets" # TAGLINE
+   description: |  # TAGLINE
+     **Fileset** entities represent sets of digital files, as well as locations  # TAGLINE
+     where they can be found on the public web. Filesets most commonly  # TAGLINE
+     represent datasets consisting of serveral data and metadata files.  # TAGLINE
+
+     See the "Catalog Style Guide" section of the guide for details and  # TAGLINE
+     semantics of what should be included in specific entity fields.  # TAGLINE
+     Specifically, the  # TAGLINE
+     [Fileset Entity Reference](https://guide.fatcat.wiki/entity_fileset.html).  # TAGLINE
  - name: webcaptures # TAGLINE
-   descriptions: "Webcapture entities" # TAGLINE
+   x-displayName: "Webcaptures" # TAGLINE
+   description: |  # TAGLINE
+     **Web Capture** entities represent archival snapshots of web pages (or  # TAGLINE
+     other web resources), which are usually complete manifestations of a  # TAGLINE
+     specific release entity. Web Captures also include a set of locations  # TAGLINE
+     (wayback replay instances or WARC files) where the capture can be found.  # TAGLINE
+
+     See the "Catalog Style Guide" section of the guide for details and  # TAGLINE
+     semantics of what should be included in specific entity fields.  # TAGLINE
+     Specifically, the  # TAGLINE
+     [Web Capture Entity Reference](https://guide.fatcat.wiki/entity_webcapture.html).  # TAGLINE
  - name: releases # TAGLINE
-   descriptions: "Release entities: individual articles, pre-prints, books" # TAGLINE
+   x-displayName: "Releases" # TAGLINE
+   description: |  # TAGLINE
+     **Release** entities represent specific published versions of a research  # TAGLINE
+     work, such as a pre-print, a journal article, a book (or chapter), or a  # TAGLINE
+     scholarly blog post. Releases are always grouped together under Works;  # TAGLINE
+     they may be published in a specific Container; they may have known  # TAGLINE
+     Creators; and there may exist known File/Fileset/WebCapture digital copies  # TAGLINE
+     of the release.  # TAGLINE
+
+     See the "Catalog Style Guide" section of the guide for details and  # TAGLINE
+     semantics of what should be included in specific entity fields.  # TAGLINE
+     Specifically, the  # TAGLINE
+     [Release Entity Reference](https://guide.fatcat.wiki/entity_release.html).  # TAGLINE
  - name: works # TAGLINE
-   descriptions: "Work entities: grouping releases which are variants of the same work" # TAGLINE
- - name: edit-lifecycle # TAGLINE
-   descriptions: "Endpoints relating to global edit submission and history" # TAGLINE
+   x-displayName: "Works" # TAGLINE
+   description: |  # TAGLINE
+     **Work** entities group several Release entities which are different  # TAGLINE
+     versions of the same abstract piece of research. For example, three  # TAGLINE
+     release entities representing the pre-print, published article, and  # TAGLINE
+     retraction stages of the same journal paper would be grouped under a  # TAGLINE
+     single work.  # TAGLINE
+
+     See the "Catalog Style Guide" section of the guide for details and  # TAGLINE
+     semantics of what should be included in specific entity fields.  # TAGLINE
+     Specifically, the  # TAGLINE
+     [Work Entity Reference](https://guide.fatcat.wiki/entity_work.html).  # TAGLINE
+ - name: editgroups # TAGLINE
+   x-displayName: "Editgroups" # TAGLINE
+   description: |  # TAGLINE
+     **Editgroups** are sets of changes, each to individual entities in the  # TAGLINE
+     catalog. Every edit must be part of an editgroup which is reviewed and  # TAGLINE
+     accepted (merged) as a whole.  # TAGLINE
+ - name: editors # TAGLINE
+   x-displayName: "Editors" # TAGLINE
+   description: |  # TAGLINE
+     **Editors** are human user accounts and bots that make changes to the  # TAGLINE
+     Fatcat catalog.  # TAGLINE
+
+     The API allows fetching (and updating) metadata about individual editors,  # TAGLINE
+     as well as fetching editor's annotation and edit history.  # TAGLINE
+ - name: changelog # TAGLINE
+   x-displayName: "Changelog" # TAGLINE
+   description: |  # TAGLINE
+     The **Changelog** is the ordered feed of editgroups which have been  # TAGLINE
+     accepted into the catalog.  # TAGLINE
+ - name: auth # TAGLINE
+   x-displayName: "Auth Methods" # TAGLINE
+   description: |  # TAGLINE
+     Helper methods and internal APIs for editor authentication.  # TAGLINE
+
+x-tagGroups:
+ - name: Entities
+   tags:
+    - containers
+    - creators
+    - files
+    - filesets
+    - webcaptures
+    - releases
+    - works
+ - name: Editing
+   tags:
+    - editors
+    - editgroups
+    - changelog
+ - name: Other
+   tags:
+    - auth
 
 # don't want these to be rust types (at least for now)
 x-fatcat-ident: &FATCATIDENT
   type: string
-  example: "q3nouwy3nnbsvo3h5klxsx4a7y"
   pattern: "[a-zA-Z2-7]{26}"
   minLength: 26
   maxLength: 26
   description: "base32-encoded unique identifier"
+x-fatcat-ident-example: &FATCATIDENTEXAMPLE
+  example: "q3nouwy3nnbsvo3h5klxsx4a7y"
 x-fatcat-uuid: &FATCATUUID
   type: string
-  example: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
   pattern: "[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
   minLength: 36
   maxLength: 36
   description: "UUID (lower-case, dash-separated, hex-encoded 128-bit)"
+x-fatcat-uuid-example: &FATCATUUIDEXAMPLE
+  example: "86daea5b-1b6b-432a-bb67-ea97795f80fe"
 x-issn: &FATCATISSN
   type: string
-  example: "1234-5678"
   pattern: "\\d{4}-\\d{3}[0-9X]"
   minLength: 9
   maxLength: 9
+x-issn-example: &FATCATISSNEXAMPLE
+  example: "1234-5678"
 x-orcid: &FATCATORCID
   type: string
-  example: "0000-0002-1825-0097"
   pattern: "\\d{4}-\\d{4}-\\d{4}-\\d{3}[\\dX]"
   minLength: 19
   maxLength: 19
+  description: "ORCiD (https://orcid.org) identifier"
+x-orcid-example: &FATCATORCIDEXAMPLE
+  example: "0000-0002-1825-0097"
 x-md5: &FATCATMD5
   type: string
-  example: "1b39813549077b2347c0f370c3864b40"
   pattern: "[a-f0-9]{32}"
   minLength: 32
   maxLength: 32
+  description: "MD5 hash of data, in hex encoding"
+x-md5-example: &FATCATMD5EXAMPLE
+  example: "1b39813549077b2347c0f370c3864b40"
 x-sha1: &FATCATSHA1
   type: string
-  example: "e9dd75237c94b209dc3ccd52722de6931a310ba3"
   pattern: "[a-f0-9]{40}"
   minLength: 40
   maxLength: 40
+  description: "SHA-1 hash of data, in hex encoding"
+x-sha1-example: &FATCATSHA1EXAMPLE
+  example: "e9dd75237c94b209dc3ccd52722de6931a310ba3"
 x-sha256: &FATCATSHA256
   type: string
-  example: "cb1c378f464d5935ddaa8de28446d82638396c61f042295d7fb85e3cccc9e452"
   pattern: "[a-f0-9]{64}"
   minLength: 64
   maxLength: 64
+  description: "SHA-256 hash of data, in hex encoding"
+x-sha256-example: &FATCATSHA256EXAMPLE
+  example: "cb1c378f464d5935ddaa8de28446d82638396c61f042295d7fb85e3cccc9e452"
 
 # Common properties across entities
 x-entity-props: &ENTITYPROPS
   state:
     type: string
     enum: ["wip", "active", "redirect", "deleted"]
+    example: "active"
   ident:
     <<: *FATCATIDENT
+    <<: *FATCATIDENTEXAMPLE
   revision:
     <<: *FATCATUUID
+    <<: *FATCATUUIDEXAMPLE
   redirect:
     <<: *FATCATIDENT
+    <<: *FATCATIDENTEXAMPLE
   extra:
     type: object
+    description: |
+      Free-form JSON metadata that will be stored with the other entity
+      metadata. See guide for (unenforced) schema conventions.
     additionalProperties: {}
   edit_extra:
     type: object
+    description: |
+      Free-form JSON metadata that will be stored with specific entity edits
+      (eg, creation/update/delete).
     additionalProperties: {}
 
 definitions:
@@ -111,8 +348,10 @@ definitions:
     properties:
       success:
         type: boolean
+        example: false
       error:
         type: string
+        example: "unexpected-thing"
       message:
         type: string
         example: "A really confusing, totally unexpected thing happened"
@@ -124,6 +363,7 @@ definitions:
     properties:
       success:
         type: boolean
+        example: true
       message:
         type: string
         example: "The computers did the thing successfully!"
@@ -134,18 +374,25 @@ definitions:
       <<: *ENTITYPROPS
       name:
         type: string
+        description: "Name of the container (eg, Journal title). Required for entity creation."
         example: "Journal of Important Results"
-        description: "Required for valid entities"
       container_type:
         type: string
-        description: "Eg, 'journal'"
+        description: "Type of container, eg 'journal' or 'proceedings'. See Guide for list of valid types."
+        example: "journal"
       publisher:
         type: string
+        description: |
+          Name of the organization or entity responsible for publication. Not
+          the complete imprint/brand.
         example: "Society of Curious Students"
       issnl:
+        description: "Linking ISSN number (ISSN-L). Should be valid and registered with issn.org"
         <<: *FATCATISSN
+        <<: *FATCATISSNEXAMPLE
       wikidata_qid:
         type: string
+        example: "Q42812"
   creator_entity:
     type: object
     # required for creation: display_name
@@ -154,15 +401,26 @@ definitions:
       display_name:
         type: string
         example: "Grace Hopper"
-        description: "Required for valid entities"
+        description: |
+          Name as should be displayed in web interface or in author lists (not
+          index/sorted). Required for valid entities.
       given_name:
         type: string
+        description: |
+          In English commonly the first name, but ordering is context and
+          culture specific.
       surname:
         type: string
+        description: |
+          In English commonly the last, or family name, but ordering is context
+          and culture specific.
       orcid:
         <<: *FATCATORCID
+        <<: *FATCATORCIDEXAMPLE
       wikidata_qid:
         type: string
+        example: "Q42812"
+        description: "Wikidata entity QID"
   file_entity:
     type: object
     properties:
@@ -171,12 +429,16 @@ definitions:
         type: integer
         example: 1048576
         format: int64
+        description: "Size of file in bytes. Non-zero."
       md5:
         <<: *FATCATMD5
+        <<: *FATCATMD5EXAMPLE
       sha1:
         <<: *FATCATSHA1
+        <<: *FATCATSHA1EXAMPLE
       sha256:
         <<: *FATCATSHA256
+        <<: *FATCATSHA256EXAMPLE
       urls:
         type: array
         items:
@@ -188,8 +450,16 @@ definitions:
         type: array
         items:
           <<: *FATCATIDENT
+          <<: *FATCATIDENTEXAMPLE
+        description: |
+          Set of identifier of release entities this file represents a full
+          manifestation of. Usually a single release, but some files contain
+          content of multiple full releases (eg, an issue of a journal).
       releases:
-        description: "Optional; GET-only"
+        description: |
+          Full release entities, included in GET responses when `releases`
+          included in `expand` parameter. Ignored if included in PUT or POST
+          requests.
         type: array
         items:
           $ref: "#/definitions/release_entity"
@@ -203,9 +473,15 @@ definitions:
         type: string
         format: url
         example: "https://example.edu/~frau/prcding.pdf"
+        description: |
+          URL/URI pointing directly to a machine retrievable copy of this exact
+          file.
       rel:
         type: string
-        example: "webarchive"
+        example: "web"
+        description: |
+          Indicates type of host this URL points to. Eg, "publisher",
+          "repository", "webarchive". See guide for list of acceptable values.
   fileset_entity:
     type: object
     properties:
@@ -223,11 +499,18 @@ definitions:
         type: array
         items:
           <<: *FATCATIDENT
+          <<: *FATCATIDENTEXAMPLE
+        description: |
+          Set of identifier of release entities this fileset represents a full
+          manifestation of. Usually a single release.
       releases:
-        description: "Optional; GET-only"
         type: array
         items:
           $ref: "#/definitions/release_entity"
+        description: |
+          Full release entities, included in GET responses when `releases`
+          included in `expand` parameter. Ignored if included in PUT or POST
+          requests.
   fileset_url:
     type: object
     required:
@@ -241,6 +524,9 @@ definitions:
       rel:
         type: string
         example: "webarchive"
+        description: |
+          Indicates type of host this URL points to. See guide for list of
+          acceptable values.
   fileset_file:
     type: object
     required:
@@ -250,19 +536,29 @@ definitions:
       path:
         type: string
         example: "img/cat.png"
+        description: |
+          Path name of file within this fileset (eg, directory)
       size:
         type: integer
         example: 1048576
         format: int64
+        description: "File size in bytes"
       md5:
         <<: *FATCATMD5
+        <<: *FATCATMD5EXAMPLE
       sha1:
         <<: *FATCATSHA1
+        <<: *FATCATSHA1EXAMPLE
       sha256:
         <<: *FATCATSHA256
+        <<: *FATCATSHA256EXAMPLE
       extra:
         type: object
         additionalProperties: {}
+        description: |
+          Free-form additional metadata about this specific file in the set.
+          Eg, `mimetype`. See guide for nomative (but unenforced) schema
+          fields.
   webcapture_entity:
     type: object
     properties:
@@ -280,19 +576,30 @@ definitions:
         type: string
         format: url
         example: "http://asheesh.org"
+        description: "Base URL of the primary resource this is a capture of"
       timestamp:
         type: string
         format: date-time
-        description: "same format as CDX line timestamp (UTC, etc). Corresponds to the overall capture timestamp. Can be the earliest or average of CDX timestamps if that makes sense."
+        description: |
+            Same format as CDX line timestamp (UTC, etc). Corresponds to the
+            overall capture timestamp. Should generally be the timestamp of
+            capture of the primary resource URL.
       release_ids:
         type: array
         items:
           <<: *FATCATIDENT
+          <<: *FATCATIDENTEXAMPLE
+        description: |
+          Set of identifier of release entities this fileset represents a full
+          manifestation of. Usually a single release.
       releases:
-        description: "Optional; GET-only"
         type: array
         items:
           $ref: "#/definitions/release_entity"
+        description: |
+          Full release entities, included in GET responses when `releases`
+          included in `expand` parameter. Ignored if included in PUT or POST
+          requests.
   webcapture_cdx_line:
     type: object
     required:
@@ -304,30 +611,46 @@ definitions:
       surt:
         type: string
         example: "org,asheesh)/apus/ch1/node15.html"
+        description: |
+          "Sortable URL" format. See guide for details.
       timestamp:
         type: string
         format: date-time
         example: "2016-09-19T17:20:24Z"
-        description: "UTC, 'Z'-terminated, second (or better) precision"
+        description: |
+          Date and time of capture, in ISO format. UTC, 'Z'-terminated, second
+          (or better) precision.
       url:
         type: string
         # NOTE: not format:url to allow alternatives
         example: "http://www.asheesh.org:80/APUS/ch1/node15.html"
+        description: |
+          Full URL/URI of resource captured.
       mimetype:
         type: string
         example: "text/html"
+        description: |
+          Mimetype of the resource at this URL. May be the Content-Type header,
+          or the actually sniffed file type.
       status_code:
         type: integer
         example: 200
         format: int64
+        description: |
+          HTTP status code. Should generally be 200, especially for the primary
+          resource, but may be 3xx (redirect) or even error codes if embedded
+          resources can not be fetched successfully.
       size:
         type: integer
         example: 1048576
         format: int64
+        description: "Resource (file) size in bytes"
       sha1:
         <<: *FATCATSHA1
+        <<: *FATCATSHA1EXAMPLE
       sha256:
         <<: *FATCATSHA256
+        <<: *FATCATSHA256EXAMPLE
   webcapture_url:
     type: object
     required:
@@ -338,9 +661,15 @@ definitions:
         type: string
         format: url
         example: "https://web.archive.org/web/"
+        description: |
+          URL/URI pointing to archive of this web resource.
       rel:
         type: string
         example: "wayback"
+        description: |
+          Type of archive endpoint. Usually `wayback` (WBM replay of primary
+          resource), or `warc` (direct URL to a WARC file containing all
+          resources of the capture). See guide for full list.
   release_entity:
     type: object
     # required for creation: title
@@ -350,80 +679,167 @@ definitions:
       <<: *ENTITYPROPS
       title:
         type: string
-        description: "Required for valid entities. The title used in citations and for display; usually English"
+        description: |
+          Required for valid entities. The title used in citations and for
+          display. Sometimes the English translation of title e even if release
+          content is not English.
       subtitle:
         type: string
-        description: "Avoid this field if possible, and merge with title; usually English"
+        description: |
+          Subtitle of release. In many cases, better to merge with title than
+          include as separate field (unless combined title would be very long).
+          See guide for details.
       original_title:
         type: string
-        description: "Title in original language (or, the language of the full text of this release)"
+        description: |
+          Title in original language if `title` field has been translated. See
+          guide for details.
       work_id:
         type: string
         example: "q3nouwy3nnbsvo3h5klxsx4a7y"
+        description: |
+          Identifier of work this release is part of. In creation (POST)
+          requests, a work entity will be created automatically if this field
+          is not set.
       container:
         $ref: "#/definitions/container_entity"
-        description: "Optional; GET-only"
+        description: |
+          Complete container entity identified by `container_id` field. Only
+          included in GET reponses when `container` included in `expand`
+          parameter; ignored in PUT or POST requests.
       files:
-        description: "Optional; GET-only"
         type: array
         items:
           $ref: "#/definitions/file_entity"
+        description: |
+          Complete file entities identified by `file_ids` field. Only
+          included in GET responses when `files` included in `expand` parameter;
+          ignored in PUT or POST requests.
       filesets:
-        description: "Optional; GET-only"
         type: array
         items:
           $ref: "#/definitions/fileset_entity"
+        description: |
+          Complete file entities identified by `filesets_ids` field. Only
+          included in GET responses when `filesets` included in `expand`
+          parameter; ignored in PUT or POST requests.
       webcaptures:
-        description: "Optional; GET-only"
         type: array
         items:
           $ref: "#/definitions/webcapture_entity"
+        description: |
+          Complete webcapture entities identified by `webcapture_ids` field.
+          Only included in GET responses when `webcaptures` included in `expand`
+          parameter; ignored in PUT or POST requests.
       container_id:
         type: string
         example: "q3nouwy3nnbsvo3h5klxsx4a7y"
+        description: |
+          Used to link this release to a container entity that the release was
+          published as part of.
       release_type:
         type: string
         example: "book"
+        description: |
+          "Type" or "medium" that this release is published as. See guide for
+          valid values.
       release_stage:
         type: string
-        example: "preprint, retracted"
+        example: "preprint"
+        description: |
+          The stage of publication of this specific release. See guide for
+          valid values and semantics.
       release_date:
         type: string
         format: date
+        description: |
+          Full date when this release was formally published. ISO format, like
+          `2019-03-05`. See guide for semantics.
       release_year:
         type: integer
         example: 2014
         format: int64
+        description: |
+          Year when this release was formally published. Must match
+          `release_date` if that field is set; this field exists because
+          sometimes only the year is known.
       withdrawn_status:
         type: string
+        example: "retracted"
+        description: |
+          Type of withdrawl or retraction of this release, if applicable. If
+          release has not been withdrawn, should be `null` (aka, not set, not
+          the string "null" or an empty string).
       withdrawn_date:
         type: string
         format: date
+        description: |
+          Full date when this release was formally withdrawn (if applicable).
+          ISO format, like `release_date`.
       withdrawn_year:
         type: integer
         example: 2014
         format: int64
+        description: |
+          Year corresponding with `withdrawn_date` like
+          `release_year`/`release_date`.
       ext_ids:
         $ref: "#/definitions/release_ext_ids"
+        description: |
+          Set of external identifiers for this release.
       volume:
         type: string
+        example: "3"
+        description: |
+          Volume number of container that this release was published in. Often
+          corresponds to the "Nth" year of publication, but can be any string.
+          See guide.
       issue:
         type: string
         example: "12"
+        description: |
+          Issue number of volume/container that this release was published in.
+          Sometimes coresponds to a month number in the year, but can be any
+          string. See guide.
       pages:
         type: string
+        example: "340-345"
+        description: |
+          Either a single page number ("first page") or a range of pages
+          separated by a dash ("-"). See guide for details.
       number:
         type: string
+        example: "RFC1337"
+        description: |
+          For, eg, technical reports, which are published in series or
+          assigned some other institutional or container-specific identifier.
       version:
         type: string
+        example: "3"
+        description: |
+          For, eg, updated technical reports or software packages, where
+          the version string may be the only field disambiguating between
+          releases.
       publisher:
         type: string
+        example: "Elsevier"
+        description: |
+          Name, usually English, of the entity or institution responsible for
+          publication of this release. Not necessarily the imprint/brand. See
+          guide.
       language:
-        description: "Two-letter RFC1766/ISO639-1 language code, with extensions"
         type: string
+        example: "en"
+        description: |
+          Primary language of the content of the full release. Two-letter
+          RFC1766/ISO639-1 language code, with some custom
+          extensions/additions. See guide.
       license_slug:
         type: string
-        description: "Short version of license name. Eg, 'CC-BY'"
+        example: "CC-BY"
+        description: |
+          Short string (slug) name of license under which release is openly
+          published (if applicable).
       contribs:
         type: array
         items:
@@ -443,40 +859,67 @@ definitions:
         type: string
         #format: custom
         example: "10.1234/abcde.789"
+        description: |
+          Digital Object Identifier (DOI), mostly for published papers and
+          datasets. Should be registered and resolvable via https://doi.org/
       wikidata_qid:
         type: string
+        example: "Q42812"
+        description: "Wikidata entity QID"
       isbn13:
         type: string
         #format: custom
+        description: |
+          ISBN-13, for books. Usually not set for chapters. ISBN-10 should be
+          converted to ISBN-13.
       pmid:
         type: string
+        example: "482132"
+        description: "PubMed Identifier"
       pmcid:
+        example: "PMC7391"
         type: string
+        description: "PubMed Central Identifier"
       core:
+        exmaple: "9234592"
         type: string
         #format: custom
+        description: "CORE (https://core.ac.uk) identifier"
       arxiv:
         type: string
+        description: "arXiv (https://arxiv.org) identifier; must include version"
       jstor:
         type: string
+        description: "JSTOR work identifier"
       ark:
         type: string
+        description: "ARK identifier"
       mag:
         type: string
+        description: "Microsoft Academic Graph identifier"
   release_abstract:
     type: object
     properties:
       sha1:
         <<: *FATCATSHA1
+        <<: *FATCATSHA1EXAMPLE
       content:
         type: string
         example: "<jats:p>Some abstract thing goes here</jats:p>"
+        description: |
+          Abstract content. May be encoded, as per `mimetype` field, but only
+          string/text content may be included.
       mimetype:
         type: string
         example: "application/xml+jats"
+        description: |
+          Mimetype of abstract contents. `text/plain` is the default if content
+          isn't encoded.
       lang:
         type: string
         example: "en"
+        description: |
+          ISO language code of the abstract. Same semantics as release `language` field.
   work_entity:
     type: object
     properties:
@@ -503,16 +946,37 @@ definitions:
     properties:
       edit_id:
           <<: *FATCATUUID
+          <<: *FATCATUUIDEXAMPLE
+          description: |
+            Unique UUID for this specific edit object.
       ident:
           <<: *FATCATIDENT
+          <<: *FATCATIDENTEXAMPLE
+          description: |
+            Fatcat identifier of the entity this edit is mutating.
       revision:
           <<: *FATCATUUID
+          <<: *FATCATUUIDEXAMPLE
+          description: |
+            Entity revision that this edit will set the entity to. May be
+            `null` in the case of deletions.
       prev_revision:
           <<: *FATCATUUID
+          <<: *FATCATUUIDEXAMPLE
+          description: |
+            Revision of entity just before this edit. May be used in the future
+            to prevent edit race conditions.
       redirect_ident:
           <<: *FATCATIDENT
+          <<: *FATCATIDENTEXAMPLE
+          description: |
+            When an edit is to merge entities (redirect one to another), this
+            is the entity fatcat identifier for the target entity.
       editgroup_id:
           <<: *FATCATIDENT
+          <<: *FATCATIDENTEXAMPLE
+          description: |
+            Editgroup identifier that this edit is part of.
       extra:
           type: object
           additionalProperties: {}
@@ -523,45 +987,94 @@ definitions:
     properties:
       editor_id:
         <<: *FATCATIDENT
+        <<: *FATCATIDENTEXAMPLE
+        description: |
+          Fatcat identifier for the editor. Can not be changed.
       username:
         type: string
         example: "zerocool93"
+        description: |
+          Username/handle (short slug-like string) to identify this editor. May
+          be changed at any time by the editor; use the `editor_id` as a
+          persistend identifer.
       is_admin:
         type: boolean
+        example: false
+        description: |
+          Whether this editor has the `admin` role.
       is_bot:
         type: boolean
+        example: false
+        description: |
+          Whether this editor is a bot (as opposed to a human making manual
+          edits)
       is_active:
         type: boolean
+        example: true
+        description: |
+          Whether this editor's account is enabled (if not API tokens and web
+          logins will not work).
   editgroup:
     type: object
     properties:
       editgroup_id:
         <<: *FATCATIDENT
+        <<: *FATCATIDENTEXAMPLE
+        description: |
+          Fatcat identifier for this editgroup. Assigned on creation.
       editor_id:
         <<: *FATCATIDENT
+        <<: *FATCATIDENTEXAMPLE
+        description: |
+          Fatcat identifer of editor that created this editgroup.
       editor:
         $ref: "#/definitions/editor"
+        description: |
+          Complete editor object identified by `container_id` field. Only
+          included in GET responses.
       changelog_index: # not returned in all contexts...
         type: integer
         example: 1048576
         format: int64
+        description: |
+          For accepted/merged editgroups, the changelog index that the accept
+          occured at. WARNING: not populated in all contexts that an editgroup
+          could be included in a response.
       created:
         type: string
         format: date-time
+        description: |
+          Timestamp when this editgroup was first created.
       submitted:
         type: string
         format: date-time
+        description: |
+          Timestamp when this editgroup was most recently submitted for review.
+          If withdrawn, or never submitted, will be `null`.
       description:
         type: string
+        description: |
+          Comment describing the changes in this editgroup. Can be updated with
+          PUT request.
       extra:
         type: object
         additionalProperties: {}
+        description: |
+          Free-form JSON metadata attached to this editgroup. Eg, metadata
+          provenance, or script user-agent details. See guide for (unenforced)
+          schema norms.
       annotations:
         type: array
         items:
           $ref: "#/definitions/editgroup_annotation"
+        description: |
+          Only included in GET responses, and not in all contexts. Do not
+          include this field in PUT or POST requests.
       edits:
         type: object
+        description: |
+          Only included in GET responses, and not in all contexts. Do not
+          include this field in PUT or POST requests.
         properties:
           containers:
             type: array
@@ -596,20 +1109,36 @@ definitions:
     properties:
       annotation_id:
         <<: *FATCATUUID
+        <<: *FATCATUUIDEXAMPLE
       editgroup_id:
         <<: *FATCATIDENT
+        <<: *FATCATIDENTEXAMPLE
+        description: |
+          Editgroup that this annotation applies to. Set automatically in
+          creations based on URL parameter.
       editor_id:
         <<: *FATCATIDENT
+        <<: *FATCATIDENTEXAMPLE
+        description: |
+          Defaults to editor created the annotation via POST request.
       editor:
         $ref: "#/definitions/editor"
+        description: |
+          Only included in GET responses; ignored in PUT or POST requests.
       created:
         type: string
         format: date-time
+        description: |
+          Timestamp when annotation was first created.
       comment_markdown:
         type: string
       extra:
         type: object
         additionalProperties: {}
+        description: |
+          Additional free-form JSON metadata that can be included as part of
+          the annotation (or even as the primary annotation itself). See guide
+          for details.
   changelog_entry:
     type: object
     required:
@@ -620,12 +1149,18 @@ definitions:
       index:
         type: integer
         format: int64
+        description: |
+          Monotonically increasing sequence number of this changelog entry.
       editgroup_id:
         type: string
         example: "q3nouwy3nnbsvo3h5klxsx4a7y"
+        description: |
+          Identifier of editgroup accepted/merged in this changelog entry.
       timestamp:
         type: string
         format: date-time
+        description: |
+          Date and time when the editgroup was accpeted.
       editgroup:
         $ref: "#/definitions/editgroup"
   release_ref:
@@ -634,48 +1169,104 @@ definitions:
       index:
         type: integer
         format: int64
+        description: |
+          Zero-indexed sequence number of this reference in the list of
+          references. Assigned automatically and used internally; don't confuse
+          with `key`.
       target_release_id:
         <<: *FATCATIDENT
+        <<: *FATCATIDENTEXAMPLE
+        description: |
+          Optional, fatcat identifier of release entity that this reference is
+          citing.
       extra:
         type: object
         additionalProperties: {}
+        description: |
+          Additional free-form JSON metadata about this citation. Generally
+          follows Citation Style Language (CSL) JSON schema. See guide for
+          details.
       key:
         type: string
+        example: "SMITH2016"
+        description: |
+          Short string used to indicate this reference from within the release
+          text; or numbering of references as typeset in the release itself.
+          Optional; don't confuse with `index` field.
       year:
         type: integer
         format: int64
+        example: 1972
+        description: |
+          Year that the cited work was published in.
       container_name:
         type: string
+        description: |
+          Name of the container (eg, journal) that the citation work was
+          published as part of. May be an acronym or full name.
       title:
         type: string
+        description:
+          Name of the work being cited.
       locator:
         type: string
         example: "p123"
+        description: |
+          Page number or other indicator of the specific subset of a work being
+          cited. Not to be confused with the first page (or page range) of an
+          entire paper or chapter being cited.
   release_contrib:
     type: object
     properties:
       index:
         type: integer
         format: int64
+        example: 0
+        description: |
+          Internally assigned zero-indexed sequence number of contribution.
+          Authors should come first; this encodes the order of attriubtion.
       creator_id:
         <<: *FATCATIDENT
+        <<: *FATCATIDENTEXAMPLE
+        description: |
+          If known, indicates the creator entity this contribution was made by.
       creator:
         $ref: "#/definitions/creator_entity"
-        description: "Optional; GET-only"
+        description: |
+          Complete creator entity. Only returned in GET responses, and only if
+          `contribs` included in the `expand` query parameter.
       raw_name:
         type: string
+        example: "Jane K. Doe"
+        description: |
+          Full name of the contributor as typeset in the release.
       given_name:
         type: string
+        example: "Jane"
+        description: |
+          In English commonly the first name, but ordering is context and
+          culture specific.
       surname:
         type: string
+        example: "Doe"
+        description: |
+          In English commonly the last, or family name, but ordering is context
+          and culture specific.
       role:
         type: string
+        example: "author"
+        description: |
+          Short string (slug) indicating type of contribution (eg, "author",
+          "translator"). See guide for list of accpeted values.
       raw_affiliation:
         type: string
         description: "Raw affiliation string as displayed in text"
       extra:
         type: object
         additionalProperties: {}
+        description: |
+          Additional free-form JSON metadata about this
+          contributor/contribution. See guide for normative schema.
   container_auto_batch:
     type: object
     required:
@@ -770,12 +1361,26 @@ definitions:
     properties:
       provider:
         type: string
+        example: "orcid"
+        description: |
+          Fatcat-specific short name (slug) for remote service being used for
+          authentication.
       sub:
         type: string
+        description: "`SUB` from OIDC protocol. Usually a URL."
+        example: "https://orcid.org"
       iss:
         type: string
+        description: "`ISS` from OIDC protocol. Usually a stable account username, number, or identifier."
+        example: "0000-0002-8593-9468"
       preferred_username:
         type: string
+        description: |
+          What it sounds like; returned by OIDC, and used as a hint when
+          creating new editor accounts. Fatcat usernames are usually this
+          string with the `provider` slug as a suffix, though some munging may
+          occur.
+        example: "bnewbold"
   auth_oidc_result:
     type: object
     required:
@@ -786,6 +1391,7 @@ definitions:
         $ref: "#/definitions/editor"
       token:
         type: string
+        example: "AgEPZGV2LmZhdGNhdC53aWtpAhYyMDE5MDEwMS1kZXYtZHVtbXkta2V5AAImZWRpdG9yX2lkID0gYWFhYWFhYWFhYWFhYmt2a2FhYWFhYWFhYWkAAht0aW1lID4gMjAxOS0wMS0wOVQwMDo1Nzo1MloAAAYgnroNha1hSftChtxHGTnLEmM/pY8MeQS/jBSV0UNvXug="
 
 x-auth-responses: &AUTHRESPONSES
   401:
@@ -824,6 +1430,11 @@ paths:
       operationId: "create_container"
       tags: # TAGLINE
         - containers # TAGLINE
+      description: |
+        Create a single Container entity as part of an existing editgroup.
+
+        Editgroup must be mutable (aka, not accepted) and editor must have
+        permission (aka, have created the editgrou p or have `admin` role).
       parameters:
         - name: entity
           in: body
@@ -844,6 +1455,15 @@ paths:
       operationId: "create_container_auto_batch"
       tags: # TAGLINE
         - containers # TAGLINE
+      description: |
+        Create a set of Container entities as part of a new editgroup, and
+        accept that editgroup in the same atomic request.
+
+        This method is mostly useful for bulk import of new entities by
+        carefully written bots. This method is more efficient than creating an
+        editgroup, several entities, then accepting the editgroup, both in
+        terms of API requests required and database load. Requires `admin`
+        role.
       parameters:
         - name: auto_batch
           in: body
@@ -869,6 +1489,8 @@ paths:
       operationId: "get_container"
       tags: # TAGLINE
         - containers # TAGLINE
+      description: |
+        Fetches a single container entity from the catalog.
       parameters:
         - name: expand
           in: query
@@ -900,6 +1522,16 @@ paths:
       operationId: "update_container"
       tags: # TAGLINE
         - containers # TAGLINE
+      description: |
+        Updates an existing entity as part of a specific (existing) editgroup.
+        The editgroup must be open for updates (aka, not accepted/merged), and
+        the editor making the requiest must have permissions (aka, must have
+        created the editgroup or have `admin` role).
+
+        This method can also be used to update an existing entity edit as part
+        of an editgroup. For example, if an entity was created in this
+        editgroup, an editor could make changes to the new entity's metadata
+        before merging.
       parameters:
         - name: entity
           in: body
@@ -919,6 +1551,12 @@ paths:
       operationId: "delete_container"
       tags: # TAGLINE
         - containers # TAGLINE
+      description: |
+        Creates a new "deletion" edit for a specific entity as part of an
+        existing editgroup.
+
+        This is not the method to use to remove an edit from an editgroup; for
+        that use `delete_container_edit`.
       security:
         - Bearer: []
       responses:
@@ -938,17 +1576,24 @@ paths:
       operationId: "get_container_revision"
       tags: # TAGLINE
         - containers # TAGLINE
+      description: |
+        Fetches a specific entity revision. Note that the returned revision
+        will not be associated with any particular fatcat identifier (even if
+        one or more identifiers do currently point to this revision). The
+        revision may even be part of an un-merged editgroup.
+
+        Revisions are immutable and can not be deleted or updated.
       parameters:
         - name: expand
           in: query
           type: string
           required: false
-          description: "List of sub-entities to expand in response. For containers, none accepted (yet)."
+          description: "List of sub-entities to expand in response. See `get_container`."
         - name: hide
           in: query
           type: string
           required: false
-          description: "List of entity fields to elide in response. For containers, none accepted (yet)."
+          description: "List of entity fields to elide in response. See `get_container`."
       responses:
         200:
           description: Found Entity Revision
@@ -966,9 +1611,13 @@ paths:
         type: integer
         format: int64
         required: false
+        description: "Maximum number of changelog entries to return"
     get:
       tags: # TAGLINE
         - containers # TAGLINE
+      description: |
+        Fetches the history of accepted edits (changelog entries) for a
+        specific entity fatcat identifier.
       operationId: "get_container_history"
       responses:
         200:
@@ -985,9 +1634,12 @@ paths:
         type: string
         required: true
     get:
+      operationId: "get_container_redirects"
       tags: # TAGLINE
         - containers # TAGLINE
-      operationId: "get_container_redirects"
+      description: |
+        Returns the set of entity identifiers which currently redirect to this
+        identifier.
       responses:
         200:
           description: Found Entity Redirects
@@ -1001,6 +1653,14 @@ paths:
       operationId: "lookup_container"
       tags: # TAGLINE
         - containers # TAGLINE
+      description: |
+        Looks for an active entity with the given external identifier. If any
+        such entity is found, returns a single complete entity. If multiple
+        entities have the same external identifier, this is considered a soft
+        catalog error, and the behavior of which entity is returned is
+        undefined.
+
+        One (and only one) external identifier should be specified per request.
       parameters:
         - name: issnl
           in: query
@@ -1008,17 +1668,18 @@ paths:
           <<: *FATCATISSN
         - name: wikidata_qid
           in: query
+          type: string
           required: false
         - name: expand
           in: query
           type: string
           required: false
-          description: "List of sub-entities to expand in response."
+          description: "List of sub-entities to expand in response. See `get_container`."
         - name: hide
           in: query
           type: string
           required: false
-          description: "List of entity fields to elide in response. For container, none accepted (yet)."
+          description: "List of entity fields to elide in response. See `get_container`."
       responses:
         200:
           description: Found Entity
@@ -1030,6 +1691,9 @@ paths:
       operationId: "get_container_edit"
       tags: # TAGLINE
         - containers # TAGLINE
+      description: |
+        Returns the entity edit object with the given identifier. This method
+        is expected to be used rarely.
       parameters:
         - name: edit_id
           in: path
@@ -1055,6 +1719,14 @@ paths:
       operationId: "delete_container_edit"
       tags: # TAGLINE
         - containers # TAGLINE
+      description: |
+        Removes a single edit from the specified editgroup. The editgroup must
+        be mutable (aka, not accepted/merged), and the editor making this
+        request must have permission (aka, have created the editgroup or hold
+        the `admin` role).
+
+        Not to be confused with the `delete_container` method, which *creates*
+        a new edit in the given editgroup.
       security:
         - Bearer: []
       responses:
@@ -1064,6 +1736,7 @@ paths:
             $ref: "#/definitions/success"
         <<: *ENTITYRESPONSES
         <<: *AUTHRESPONSES
+
   /editgroup/{editgroup_id}/creator:
     parameters:
       - name: editgroup_id
@@ -1129,7 +1802,7 @@ paths:
           in: query
           type: string
           required: false
-          description: "List of entity fields to elide in response. For containers, none accepted (yet)."
+          description: "List of entity fields to elide in response. For creators, none accepted (yet)."
       responses:
         200:
           description: Found Entity
@@ -1193,12 +1866,15 @@ paths:
           in: query
           type: string
           required: false
-          description: "List of sub-entities to expand in response. For creators, none accepted (yet)."
+          description: |
+            List of sub-entities to expand in response. See `get_creator`,
+            though note that identifier-based expansions (like `releases`) will
+            always be empty for revisions.
         - name: hide
           in: query
           type: string
           required: false
-          description: "List of entity fields to elide in response. For creators, none accepted (yet)."
+          description: "List of entity fields to elide in response. See `get_creator`."
       responses:
         200:
           description: Found Entity Revision
@@ -1238,11 +1914,14 @@ paths:
         in: query
         type: string
         required: false
-        description: "List of entity fields to elide in response. For creators, none implemented yet."
+        description: "List of entity fields to elide in response. See `get_release`."
     get:
       operationId: "get_creator_releases"
       tags: # TAGLINE
         - creators # TAGLINE
+      description: |
+        Returns the set of Release entities having a `contrib` entry pointing
+        to the creator entity.
       responses:
         200:
           description: Found
@@ -1258,9 +1937,9 @@ paths:
         type: string
         required: true
     get:
+      operationId: "get_creator_redirects"
       tags: # TAGLINE
         - creators # TAGLINE
-      operationId: "get_creator_redirects"
       responses:
         200:
           description: Found Entity Redirects
@@ -1281,17 +1960,18 @@ paths:
           <<: *FATCATORCID
         - name: wikidata_qid
           in: query
+          type: string
           required: false
         - name: expand
           in: query
           type: string
           required: false
-          description: "List of sub-entities to expand in response."
+          description: "List of sub-entities to expand in response. See `get_creator`."
         - name: hide
           in: query
           type: string
           required: false
-          description: "List of entity fields to elide in response. For creator, none accepted (yet)."
+          description: "List of entity fields to elide in response. See `get_creator`."
       responses:
         200:
           description: Found Entity
@@ -1337,6 +2017,7 @@ paths:
             $ref: "#/definitions/success"
         <<: *ENTITYRESPONSES
         <<: *AUTHRESPONSES
+
   /editgroup/{editgroup_id}/file:
     parameters:
       - name: editgroup_id
@@ -1466,12 +2147,12 @@ paths:
           in: query
           type: string
           required: false
-          description: "List of sub-entities to expand in response. For files, none accepted (yet)."
+          description: "List of sub-entities to expand in response. See `get_file`."
         - name: hide
           in: query
           type: string
           required: false
-          description: "List of entity fields to elide in response. For files, none accepted (yet)."
+          description: "List of entity fields to elide in response. See `get_file`."
       responses:
         200:
           description: Found Entity Revision
@@ -1508,9 +2189,9 @@ paths:
         type: string
         required: true
     get:
+      operationId: "get_file_redirects"
       tags: # TAGLINE
         - files # TAGLINE
-      operationId: "get_file_redirects"
       responses:
         200:
           description: Found Entity Redirects
@@ -1541,12 +2222,12 @@ paths:
           in: query
           type: string
           required: false
-          description: "List of sub-entities to expand in response."
+          description: "List of sub-entities to expand in response. See `get_file`."
         - name: hide
           in: query
           type: string
           required: false
-          description: "List of entity fields to elide in response. For files, none accepted (yet)."
+          description: "List of entity fields to elide in response. See `get_file`."
       responses:
         200:
           description: Found Entity
@@ -1592,6 +2273,7 @@ paths:
             $ref: "#/definitions/success"
         <<: *ENTITYRESPONSES
         <<: *AUTHRESPONSES
+
   /editgroup/{editgroup_id}/fileset:
     parameters:
       - name: editgroup_id
@@ -1721,12 +2403,12 @@ paths:
           in: query
           type: string
           required: false
-          description: "List of sub-entities to expand in response. For filesets, none accepted (yet)."
+          description: "List of sub-entities to expand in response. See `get_fileset`."
         - name: hide
           in: query
           type: string
           required: false
-          description: "List of entity fields to elide in response. For filesets, 'manifest' is accepted."
+          description: "List of entity fields to elide in response. See `get_fileset`."
       responses:
         200:
           description: Found Entity Revision
@@ -1763,9 +2445,9 @@ paths:
         type: string
         required: true
     get:
+      operationId: "get_fileset_redirects"
       tags: # TAGLINE
         - filesets # TAGLINE
-      operationId: "get_fileset_redirects"
       responses:
         200:
           description: Found Entity Redirects
@@ -1813,6 +2495,7 @@ paths:
             $ref: "#/definitions/success"
         <<: *ENTITYRESPONSES
         <<: *AUTHRESPONSES
+
   /editgroup/{editgroup_id}/webcapture:
     parameters:
       - name: editgroup_id
@@ -1942,12 +2625,12 @@ paths:
           in: query
           type: string
           required: false
-          description: "List of sub-entities to expand in response. For webcaptures, none accepted (yet)."
+          description: "List of sub-entities to expand in response. See `get_webcapture`."
         - name: hide
           in: query
           type: string
           required: false
-          description: "List of entity fields to elide in response. For webcaptures, 'cdx' is accepted."
+          description: "List of entity fields to elide in response. See `get_webcapture`."
       responses:
         200:
           description: Found Entity Revision
@@ -1984,9 +2667,9 @@ paths:
         type: string
         required: true
     get:
+      operationId: "get_webcapture_redirects"
       tags: # TAGLINE
         - webcaptures # TAGLINE
-      operationId: "get_webcapture_redirects"
       responses:
         200:
           description: Found Entity Redirects
@@ -2034,6 +2717,7 @@ paths:
             $ref: "#/definitions/success"
         <<: *ENTITYRESPONSES
         <<: *AUTHRESPONSES
+
   /editgroup/{editgroup_id}/release:
     parameters:
       - name: editgroup_id
@@ -2044,6 +2728,13 @@ paths:
       operationId: "create_release"
       tags: # TAGLINE
         - releases # TAGLINE
+      description: |
+        Create a single Release entity as part of an existing editgroup. If the
+        `work_id` field is not set, a work entity will be created automatically
+        and this field set pointing to the new work.
+
+        Editgroup must be mutable (aka, not accepted) and editor must have
+        permission (aka, have created the editgrou p or have `admin` role).
       parameters:
         - name: entity
           in: body
@@ -2064,6 +2755,15 @@ paths:
       operationId: "create_release_auto_batch"
       tags: # TAGLINE
         - releases # TAGLINE
+      description: |
+        Create a set of Release entities as part of a new editgroup, and
+        accept that editgroup in the same atomic request.
+
+        This method is mostly useful for bulk import of new entities by
+        carefully written bots. This method is more efficient than creating an
+        editgroup, several entities, then accepting the editgroup, both in
+        terms of API requests required and database load. Requires `admin`
+        role.
       parameters:
         - name: auto_batch
           in: body
@@ -2089,17 +2789,23 @@ paths:
       operationId: "get_release"
       tags: # TAGLINE
         - releases # TAGLINE
+      description: |
+        Fetches a single Release entity from the catalog.
       parameters:
         - name: expand
           in: query
           type: string
           required: false
-          description: "List of sub-entities to expand in response. For releases, 'files', 'filesets, 'webcaptures', 'container', and 'creators' are valid."
+          description: |
+            List of sub-entities to expand in response. For releases, 'files',
+            'filesets, 'webcaptures', 'container', and 'creators' are valid.
         - name: hide
           in: query
           type: string
           required: false
-          description: "List of entity fields to elide in response. For releases, 'abstracts', 'refs', and 'contribs' are valid."
+          description: |
+            List of entity fields to elide in response (for efficiency). For
+            releases, 'abstracts', 'refs', and 'contribs' are valid.
       responses:
         200:
           description: Found Entity
@@ -2120,6 +2826,16 @@ paths:
       operationId: "update_release"
       tags: # TAGLINE
         - releases # TAGLINE
+      description: |
+        Updates an existing entity as part of a specific (existing) editgroup.
+        The editgroup must be open for updates (aka, not accepted/merged), and
+        the editor making the requiest must have permissions (aka, must have
+        created the editgroup or have `admin` role).
+
+        This method can also be used to update an existing entity edit as part
+        of an editgroup. For example, if an entity was created in this
+        editgroup, an editor could make changes to the new entity's metadata
+        before merging.
       parameters:
         - name: entity
           in: body
@@ -2139,6 +2855,12 @@ paths:
       operationId: "delete_release"
       tags: # TAGLINE
         - releases # TAGLINE
+      description: |
+        Creates a new "deletion" edit for a specific entity as part of an
+        existing editgroup.
+
+        This is not the method to use to remove an edit from an editgroup; for
+        that use `delete_release_edit`.
       security:
         - Bearer: []
       responses:
@@ -2158,17 +2880,27 @@ paths:
       operationId: "get_release_revision"
       tags: # TAGLINE
         - releases # TAGLINE
+      description: |
+        Fetches a specific entity revision. Note that the returned revision
+        will not be associated with any particular fatcat identifier (even if
+        one or more identifiers do currently point to this revision). The
+        revision may even be part of an un-merged editgroup.
+
+        Revisions are immutable and can not be deleted or updated.
       parameters:
         - name: expand
           in: query
           type: string
           required: false
-          description: "List of sub-entities to expand in response. For releases, none accepted (yet)."
+          description:
+            List of sub-entities to expand in response. See `get_release`,
+            though note that identifier-based exapansions like `file` will
+            always be empty for revisions.
         - name: hide
           in: query
           type: string
           required: false
-          description: "List of entity fields to elide in response. For releases, none accepted (yet)."
+          description: "List of entity fields to elide in response. See `get_release`."
       responses:
         200:
           description: Found Entity Revision
@@ -2190,6 +2922,9 @@ paths:
       operationId: "get_release_history"
       tags: # TAGLINE
         - releases # TAGLINE
+      description: |
+        Fetches the history of accepted edits (changelog entries) for a
+        specific entity fatcat identifier.
       responses:
         200:
           description: Found Entity History
@@ -2208,11 +2943,14 @@ paths:
         in: query
         type: string
         required: false
-        description: "List of entity fields to elide in response. For files, none accepted (yet)."
+        description: "List of entity fields to elide in response. See `get_file`."
     get:
       operationId: "get_release_files"
       tags: # TAGLINE
         - releases # TAGLINE
+      description: |
+        Returns the set of File entities that have a `release_id` pointing to
+        this release entity.
       responses:
         200:
           description: Found
@@ -2231,11 +2969,14 @@ paths:
         in: query
         type: string
         required: false
-        description: "List of entity fields to elide in response. For filesets, 'manifest' is valid."
+        description: "List of entity fields to elide in response. See `get_fileset`."
     get:
       operationId: "get_release_filesets"
       tags: # TAGLINE
         - releases # TAGLINE
+      description: |
+        Returns the set of Fileset entities that have a `release_id` pointing to
+        this release entity.
       responses:
         200:
           description: Found
@@ -2254,11 +2995,14 @@ paths:
         in: query
         type: string
         required: false
-        description: "List of entity fields to elide in response. For webcaptures, 'cdx' is valid."
+        description: "List of entity fields to elide in response. See `get_webcapture`."
     get:
       operationId: "get_release_webcaptures"
       tags: # TAGLINE
         - releases # TAGLINE
+      description: |
+        Returns the set of Web Capture entities that have a `release_id`
+        pointing to this release entity.
       responses:
         200:
           description: Found
@@ -2274,9 +3018,12 @@ paths:
         type: string
         required: true
     get:
+      operationId: "get_release_redirects"
       tags: # TAGLINE
         - releases # TAGLINE
-      operationId: "get_release_redirects"
+      description: |
+        Returns the set of entity identifiers which currently redirect to this
+        identifier.
       responses:
         200:
           description: Found Entity Redirects
@@ -2290,7 +3037,16 @@ paths:
       operationId: "lookup_release"
       tags: # TAGLINE
         - releases # TAGLINE
+      description: |
+        Looks for an active entity with the given external identifier. If any
+        such entity is found, returns a single complete entity. If multiple
+        entities have the same external identifier, this is considered a soft
+        catalog error, and the behavior of which entity is returned is
+        undefined.
+
+        One (and only one) external identifier should be specified per request.
       parameters:
+        # TODO: use identifier types here
         - name: doi
           in: query
           type: string
@@ -2335,12 +3091,12 @@ paths:
           in: query
           type: string
           required: false
-          description: "List of sub-entities to expand in response."
+          description: "List of sub-entities to expand in response. See `get_release`."
         - name: hide
           in: query
           type: string
           required: false
-          description: "List of sub-entities to expand in response. For releases, 'files', 'filesets, 'webcaptures', 'container', and 'creators' are valid."
+          description: "List of sub-entities to elide in response. See `get_release`."
       responses:
         200:
           description: Found Entity
@@ -2352,6 +3108,9 @@ paths:
       operationId: "get_release_edit"
       tags: # TAGLINE
         - releases # TAGLINE
+      description: |
+        Returns the entity edit object with the given identifier. This method
+        is expected to be used rarely.
       parameters:
         - name: edit_id
           in: path
@@ -2377,6 +3136,14 @@ paths:
       operationId: "delete_release_edit"
       tags: # TAGLINE
         - releases # TAGLINE
+      description: |
+        Removes a single edit from the specified editgroup. The editgroup must
+        be mutable (aka, not accepted/merged), and the editor making this
+        request must have permission (aka, have created the editgroup or hold
+        the `admin` role).
+
+        Not to be confused with the `delete_container` method, which *creates*
+        a new edit in the given editgroup.
       security:
         - Bearer: []
       responses:
@@ -2386,6 +3153,7 @@ paths:
             $ref: "#/definitions/success"
         <<: *ENTITYRESPONSES
         <<: *AUTHRESPONSES
+
   /editgroup/{editgroup_id}/work:
     parameters:
       - name: editgroup_id
@@ -2395,7 +3163,7 @@ paths:
     post:
       operationId: "create_work"
       tags: # TAGLINE
-        - releases # TAGLINE
+        - works # TAGLINE
       parameters:
         - name: entity
           in: body
@@ -2515,12 +3283,15 @@ paths:
           in: query
           type: string
           required: false
-          description: "List of sub-entities to expand in response. For works, none accepted (yet)."
+          description:
+            List of sub-entities to expand in response. See `get_work`, though
+            note that identifier-based expansions like `releases` will always
+            be empty for revisions.
         - name: hide
           in: query
           type: string
           required: false
-          description: "List of entity fields to elide in response. For works, none accepted (yet)."
+          description: "List of entity fields to elide in response. See `get_work`."
       responses:
         200:
           description: Found Entity Revision
@@ -2557,9 +3328,9 @@ paths:
         type: string
         required: true
     get:
+      operationId: "get_work_redirects"
       tags: # TAGLINE
         - works # TAGLINE
-      operationId: "get_work_redirects"
       responses:
         200:
           description: Found Entity Redirects
@@ -2578,11 +3349,14 @@ paths:
         in: query
         type: string
         required: false
-        description: "List of entity fields to elide in response. For works, none implemented yet."
+        description: "List of entity fields to elide in response. See `get_release`."
     get:
       operationId: "get_work_releases"
       tags: # TAGLINE
         - works # TAGLINE
+      description: |
+        Returns the set of release entities that are part of this work (aka,
+        have `work_id` pointing to this work entity).
       responses:
         200:
           description: Found
@@ -2630,6 +3404,7 @@ paths:
             $ref: "#/definitions/success"
         <<: *ENTITYRESPONSES
         <<: *AUTHRESPONSES
+
   /editor/{editor_id}:
     parameters:
       - name: editor_id
@@ -2638,6 +3413,11 @@ paths:
         required: true
     get:
       operationId: "get_editor"
+      tags: # TAGLINE
+        - editors # TAGLINE
+      description: |
+        Returns an editor object, including metadata such as the username,
+        type, and role of editor.
       responses:
         200:
           description: Found
@@ -2657,6 +3437,14 @@ paths:
             $ref: "#/definitions/error_response"
     put:
       operationId: "update_editor"
+      tags: # TAGLINE
+        - editors # TAGLINE
+      description: |
+        Allows metadata changes to some editor fields, such as the username.
+
+        Changes require authentication and permissions. An editor can change
+        their own username; changes to role flags require the `admin` role by
+        the editor making the request.
       parameters:
        - name: editor
          in: body
@@ -2691,6 +3479,11 @@ paths:
         required: true
     get:
       operationId: "get_editor_editgroups"
+      tags: # TAGLINE
+        - editors # TAGLINE
+      description: |
+        Returns a set of editgroups created by the given editor, regardless of
+        the status (accepted/submitted) of the editgroups.
       parameters:
         - name: limit
           in: query
@@ -2702,11 +3495,19 @@ paths:
           type: string
           format: date-time
           required: false
+          description: |
+            Return only editgroups created *before* the given timestamp (not
+            inclusive). Editgroups will be sorted by creation time in
+            descending order (most recent first). For use in pagination.
         - name: since
           in: query
           type: string
           format: date-time
           required: false
+          description: |
+            Return only editgroups created *after* the given timestamp (not
+            inclusive). Editgroups will be sorted by creation time in ascending
+            order (most recent last). For use in pagination.
       responses:
         200:
           description: Found
@@ -2735,23 +3536,34 @@ paths:
     get:
       operationId: "get_editor_annotations"
       tags: # TAGLINE
-        - edit-lifecycle # TAGLINE
+        - editors # TAGLINE
+      description: |
+        Fetches a list of annotations made by a particular editor.
       parameters:
         - name: limit
           in: query
           type: integer
           format: int64
           required: false
+          description: "Maximum number (count) of annotations to return in response"
         - name: before
           in: query
           type: string
           format: date-time
           required: false
+          description: |
+            Return only annotations made *before* the given timestamp (not
+            inclusive). Annotations will be sorted by creation time in
+            descending order (most recent first). For use in pagination.
         - name: since
           in: query
           type: string
           format: date-time
           required: false
+          description: |
+            Return only annotations made *after* the given timestamp (not
+            inclusive). Annotations will be sorted by creation time in
+            ascending order (most recent last). For use in pagination.
       responses:
         200:
           description: Success
@@ -2772,11 +3584,15 @@ paths:
           schema:
             $ref: "#/definitions/error_response"
         <<: *AUTHRESPONSES
+
   /editgroup:
     post:
       operationId: "create_editgroup"
       tags: # TAGLINE
-        - edit-lifecycle # TAGLINE
+        - editgroups # TAGLINE
+      description: |
+        Creates a new editgroup. By default the editor making this request will
+        be the author of the editgroup.
       parameters:
         - name: editgroup
           in: body
@@ -2812,7 +3628,13 @@ paths:
     get:
       operationId: "get_editgroup"
       tags: # TAGLINE
-        - edit-lifecycle # TAGLINE
+        - editgroups # TAGLINE
+      description: |
+        Returns a single editgroup object.
+
+        Unlike some similar methods, this method will return a full/expanded
+        editgroup object, which includes edit lists of each entity type (though
+        will not include the complete entity objects).
       responses:
         200:
           description: Found
@@ -2832,6 +3654,14 @@ paths:
             $ref: "#/definitions/error_response"
     put:
       operationId: "update_editgroup"
+      tags: # TAGLINE
+        - editgroups # TAGLINE
+      description: |
+        Updates metadata for a single editgroup object. Note that only metadata
+        fields such as the `description` or `extra` metadata can be changed
+        with this method; it does not allow adding or removing edits to the
+        editgroup (for that use the individual entity create/update/delete
+        methods).
       security:
         - Bearer: []
       parameters:
@@ -2871,7 +3701,11 @@ paths:
     post:
       operationId: "accept_editgroup"
       tags: # TAGLINE
-        - edit-lifecycle # TAGLINE
+        - editgroups # TAGLINE
+      description: |
+        Accept ("merge") the given editgroup into the catalog. The editgroup
+        must be open (not already accepted), and the editor making this request
+        must have the `admin` role.
       security:
         - Bearer: []
       responses:
@@ -2905,13 +3739,15 @@ paths:
     get:
       operationId: "get_editgroup_annotations"
       tags: # TAGLINE
-        - edit-lifecycle # TAGLINE
+        - editgroups # TAGLINE
+      description:
+        Returns a list of annotations made to a specific editgroup.
       parameters:
         - name: expand
           in: query
           type: string
           required: false
-          description: "List of sub-entities to expand in response. For editgroups: 'editors'"
+          description: "List of sub-entities to expand in response. For editgroup annotations: 'editors'"
       responses:
         200:
           description: Success
@@ -2941,7 +3777,12 @@ paths:
     post:
       operationId: "create_editgroup_annotation"
       tags: # TAGLINE
-        - edit-lifecycle # TAGLINE
+        - editgroups # TAGLINE
+      description: |
+        Submits a new annotation to the specified editgroup.
+
+        The editgroup must be open (not already accepted). The annotation will
+        automatically have authorship of the editor making this request.
       security:
         - Bearer: []
       parameters:
@@ -2971,6 +3812,12 @@ paths:
   /editgroup/reviewable:
     get:
       operationId: "get_editgroups_reviewable"
+      tags: # TAGLINE
+        - editgroups # TAGLINE
+      description: |
+        Returns a set of editgroups which have been submitted but not yet accepted.
+
+        Query parameters can be used to sort and paginate the list returned.
       parameters:
         - name: expand
           in: query
@@ -2982,16 +3829,25 @@ paths:
           type: integer
           format: int64
           required: false
+          description: "Maximum number of reviewable editgroups to return in response"
         - name: before
           in: query
           type: string
           format: date-time
           required: false
+          description: |
+            Return only reviewable editgroups submitted *before* the given
+            timestamp (not inclusive). Editgroups will be sorted by submission
+            time in descending order (most recent first). For use in pagination.
         - name: since
           in: query
           type: string
           format: date-time
           required: false
+          description: |
+            Return only reviewable editgroups submitted *after* the given
+            timestamp (not inclusive). Editgroups will be sorted by submission
+            time in ascending order (most recent last). For use in pagination.
       responses:
         200:
           description: Found
@@ -3018,10 +3874,27 @@ paths:
         type: integer
         format: int64
         required: false
+        description: "Maximum count of changelog entries to return in response"
     get:
       operationId: "get_changelog"
       tags: # TAGLINE
-        - edit-lifecycle # TAGLINE
+        - changelog # TAGLINE
+      description: |
+        Returns a list of the most recent changelog entries accepted (merged)
+        into the catalog.
+
+        List is sorted by changelog index in descending order. Note that the
+        accepted timestamp roughly corresponds to order, but not strictly;
+        there exist out-of-order timestamps on the order of several seconds.
+
+        As a known database issue, it is technically possible for there to be a
+        gap in changelog index numbers (aka, a missing changelog entry). There
+        are no currently known gaps and this is considered a bug that will be
+        addressed.
+
+        There are millions of entries; to paginate through all of them, use
+        this method to discover the highest existing entry number, then request
+        the entries using `get_changelog_entry` one at a time.
       responses:
         200:
           description: Success
@@ -3044,10 +3917,18 @@ paths:
         type: integer
         format: int64
         required: true
+        description: "Changelog index of entry to return"
     get:
       operationId: "get_changelog_entry"
       tags: # TAGLINE
-        - edit-lifecycle # TAGLINE
+        - changelog # TAGLINE
+      description: |
+        Returns a single changelog entry.
+
+        As a known database issue, it is technically possible for there to be a
+        gap in changelog index numbers (aka, a missing changelog entry). There
+        are no currently known gaps and this is considered a bug that will be
+        addressed.
       responses:
         200:
           description: Found Changelog Entry
@@ -3069,6 +3950,18 @@ paths:
     post:
       operationId: "auth_oidc"
       tags: # TAGLINE
+        - auth  # TAGLINE
+      description: |
+        Login or create editor account using OIDC metadata (internal method).
+
+        This method is used by privileged front-end tools (like the web
+        interface service) to process editor logins using OpenID Connect (OIDC)
+        and/or OAuth. Most accounts (including tool and bot accounts) do not
+        have sufficient privileges to call this method, which requires the
+        `admin` role.
+
+        The method returns an API token; the HTTP status code indicates whether
+        an existing account was logged in, or a new account was created.
       security:
         # required admin privs
         - Bearer: []
@@ -3104,6 +3997,11 @@ paths:
     get:
       operationId: "auth_check"
       tags: # TAGLINE
+        - auth  # TAGLINE
+      description: |
+        Verify that authentication (API token) is working as expected. The
+        optional `role` parameter can be used to verify that the current
+        account (editor) has permissions for the given role.
       security:
         # required admin privs
         - Bearer: []