rename rust crate fatcat-api-spec -> fatcat-openapi

1 files changed, 198 insertions, 0 deletions

diff --git a/rust/fatcat-openapi/README.md b/rust/fatcat-openapi/README.md
new file mode 100644
index 00000000..9565e2c7
--- /dev/null
+++ b/rust/fatcat-openapi/README.md
@@ -0,0 +1,198 @@
+# Rust API for fatcat
+
+A scalable, versioned, API-oriented catalog of bibliographic entities and file metadata
+
+## Overview
+This client/server was generated by the [swagger-codegen]
+(https://github.com/swagger-api/swagger-codegen) project.
+By using the [OpenAPI-Spec](https://github.com/OAI/OpenAPI-Specification) from a remote server, you can easily generate a server stub.
+-
+
+To see how to make this your own, look here:
+
+[README](https://github.com/swagger-api/swagger-codegen/blob/master/README.md)
+
+- API version: 0.3.0
+- Build date: 2019-09-06T02:00:55.433Z
+
+This autogenerated project defines an API crate `fatcat` which contains:
+* An `Api` trait defining the API in Rust.
+* Data types representing the underlying data model.
+* A `Client` type which implements `Api` and issues HTTP requests for each operation.
+* A router which accepts HTTP requests and invokes the appropriate `Api` method for each operation.
+
+It also contains an example server and client which make use of `fatcat`:
+* The example server starts up a web server using the `fatcat` router,
+  and supplies a trivial implementation of `Api` which returns failure for every operation.
+* The example client provides a CLI which lets you invoke any single operation on the
+  `fatcat` client by passing appropriate arguments on the command line.
+
+You can use the example server and client as a basis for your own code.
+See below for [more detail on implementing a server](#writing-a-server).
+
+
+## Examples
+
+Run examples with:
+
+```
+cargo run --example <example-name>
+```
+
+To pass in arguments to the examples, put them after `--`, for example:
+
+```
+cargo run --example client -- --help
+```
+
+### Running the server
+To run the server, follow these simple steps:
+
+```
+cargo run --example server
+```
+
+### Running a client
+To run a client, follow one of the following simple steps:
+
+```
+cargo run --example client CreateContainer
+cargo run --example client CreateContainerAutoBatch
+cargo run --example client DeleteContainer
+cargo run --example client DeleteContainerEdit
+cargo run --example client GetContainer
+cargo run --example client GetContainerEdit
+cargo run --example client GetContainerHistory
+cargo run --example client GetContainerRedirects
+cargo run --example client GetContainerRevision
+cargo run --example client LookupContainer
+cargo run --example client UpdateContainer
+cargo run --example client CreateCreator
+cargo run --example client CreateCreatorAutoBatch
+cargo run --example client DeleteCreator
+cargo run --example client DeleteCreatorEdit
+cargo run --example client GetCreator
+cargo run --example client GetCreatorEdit
+cargo run --example client GetCreatorHistory
+cargo run --example client GetCreatorRedirects
+cargo run --example client GetCreatorReleases
+cargo run --example client GetCreatorRevision
+cargo run --example client LookupCreator
+cargo run --example client UpdateCreator
+cargo run --example client AuthCheck
+cargo run --example client AuthOidc
+cargo run --example client GetEditgroupsReviewable
+cargo run --example client GetEditor
+cargo run --example client GetEditorEditgroups
+cargo run --example client UpdateEditgroup
+cargo run --example client UpdateEditor
+cargo run --example client AcceptEditgroup
+cargo run --example client CreateEditgroup
+cargo run --example client CreateEditgroupAnnotation
+cargo run --example client GetChangelog
+cargo run --example client GetChangelogEntry
+cargo run --example client GetEditgroup
+cargo run --example client GetEditgroupAnnotations
+cargo run --example client GetEditorAnnotations
+cargo run --example client CreateFile
+cargo run --example client CreateFileAutoBatch
+cargo run --example client DeleteFile
+cargo run --example client DeleteFileEdit
+cargo run --example client GetFile
+cargo run --example client GetFileEdit
+cargo run --example client GetFileHistory
+cargo run --example client GetFileRedirects
+cargo run --example client GetFileRevision
+cargo run --example client LookupFile
+cargo run --example client UpdateFile
+cargo run --example client CreateFileset
+cargo run --example client CreateFilesetAutoBatch
+cargo run --example client DeleteFileset
+cargo run --example client DeleteFilesetEdit
+cargo run --example client GetFileset
+cargo run --example client GetFilesetEdit
+cargo run --example client GetFilesetHistory
+cargo run --example client GetFilesetRedirects
+cargo run --example client GetFilesetRevision
+cargo run --example client UpdateFileset
+cargo run --example client CreateRelease
+cargo run --example client CreateReleaseAutoBatch
+cargo run --example client CreateWork
+cargo run --example client DeleteRelease
+cargo run --example client DeleteReleaseEdit
+cargo run --example client GetRelease
+cargo run --example client GetReleaseEdit
+cargo run --example client GetReleaseFiles
+cargo run --example client GetReleaseFilesets
+cargo run --example client GetReleaseHistory
+cargo run --example client GetReleaseRedirects
+cargo run --example client GetReleaseRevision
+cargo run --example client GetReleaseWebcaptures
+cargo run --example client LookupRelease
+cargo run --example client UpdateRelease
+cargo run --example client CreateWebcapture
+cargo run --example client CreateWebcaptureAutoBatch
+cargo run --example client DeleteWebcapture
+cargo run --example client DeleteWebcaptureEdit
+cargo run --example client GetWebcapture
+cargo run --example client GetWebcaptureEdit
+cargo run --example client GetWebcaptureHistory
+cargo run --example client GetWebcaptureRedirects
+cargo run --example client GetWebcaptureRevision
+cargo run --example client UpdateWebcapture
+cargo run --example client CreateWorkAutoBatch
+cargo run --example client DeleteWork
+cargo run --example client DeleteWorkEdit
+cargo run --example client GetWork
+cargo run --example client GetWorkEdit
+cargo run --example client GetWorkHistory
+cargo run --example client GetWorkRedirects
+cargo run --example client GetWorkReleases
+cargo run --example client GetWorkRevision
+cargo run --example client UpdateWork
+```
+
+### HTTPS
+The examples can be run in HTTPS mode by passing in the flag `--https`, for example:
+
+```
+cargo run --example server -- --https
+```
+
+This will use the keys/certificates from the examples directory. Note that the server chain is signed with
+`CN=localhost`.
+
+
+## Writing a server
+
+The server example is designed to form the basis for implementing your own server. Simply follow these steps.
+
+* Set up a new Rust project, e.g., with `cargo init --bin`.
+* Insert `fatcat` into the `members` array under [workspace] in the root `Cargo.toml`, e.g., `members = [ "fatcat" ]`.
+* Add `fatcat = {version = "0.3.0", path = "fatcat"}` under `[dependencies]` in the root `Cargo.toml`.
+* Copy the `[dependencies]` and `[dev-dependencies]` from `fatcat/Cargo.toml` into the root `Cargo.toml`'s `[dependencies]` section.
+  * Copy all of the `[dev-dependencies]`, but only the `[dependencies]` that are required by the example server. These should be clearly indicated by comments.
+  * Remove `"optional = true"` from each of these lines if present.
+
+Each autogenerated API will contain an implementation stub and main entry point, which should be copied into your project the first time:
+```
+cp fatcat/examples/server.rs src/main.rs
+cp fatcat/examples/server_lib/mod.rs src/lib.rs
+cp fatcat/examples/server_lib/server.rs src/server.rs
+```
+
+Now
+
+* From `src/main.rs`, remove the `mod server_lib;` line, and uncomment and fill in the `extern crate` line with the name of this server crate.
+* Move the block of imports "required by the service library" from `src/main.rs` to `src/lib.rs` and uncomment.
+* Change the `let server = server::Server {};` line to `let server = SERVICE_NAME::server().unwrap();` where `SERVICE_NAME` is the name of the server crate.
+* Run `cargo build` to check it builds.
+* Run `cargo fmt` to reformat the code.
+* Commit the result before making any further changes (lest format changes get confused with your own updates).
+
+Now replace the implementations in `src/server.rs` with your own code as required.
+
+## Updating your server to track API changes
+
+Later, if the API changes, you can copy new sections  from the autogenerated API stub into your implementation.
+Alternatively, implement the now-missing methods based on the compiler's error messages.