feat: starting out with v1 API OpenAPI (#492)

Cargo.toml

@@ -27,8 +27,8 @@ biocommons-bioutils = "0.1.0"
 boolvec = "0.2"
 byteorder = "1.4"
 chrono = { version = "0.4", features = ["serde"] }
-clap = { version = "4.5", features = ["derive", "env"] }
 clap-verbosity-flag = "2.2"
+clap = { version = "4.5", features = ["derive", "env"] }
 csv = "1.2"
 enum-map = { version = "2.7.3", features = ["serde"] }
 env_logger = "0.11"
@@ -42,16 +42,19 @@ pbjson = "0.7"
 pbjson-types = "0.7"
 prost = "0.13"
 rayon = "1.8"
-rocksdb = { version = "0.22", features = ["multi-threaded-cf"] }
 rocksdb-utils-lookup = "0.4"
+rocksdb = { version = "0.22", features = ["multi-threaded-cf"] }
 rustc-hash = "2.0.0"
-serde = { version = "1.0", features = ["derive"] }
 serde_json = { version = "1.0", features = ["preserve_order"] }
+serde = { version = "1.0", features = ["derive"] }
 serde_with = { version = "3.9", features = ["alloc", "macros", "indexmap_2"], default-features = false }
+serde_yaml = "0.9"
 strum = { version = "0.26", features = ["strum_macros", "derive"] }
 thiserror = "1.0"
 tracing = "0.1"
 tracing-subscriber = "0.3"
+utoipa-swagger-ui = { version = "7.1.0", features = ["actix-web"] }
+utoipa = { version = "4.2", features = ["actix_extras", "chrono", "indexmap", "preserve_order", "yaml"] }
 
 [dependencies.noodles]
 version = "0.77.0"

build.rs

@@ -14,6 +14,7 @@ fn main() -> Result<(), anyhow::Error> {
         "annonars/clinvar/minimal.proto",
         "annonars/clinvar/per_gene.proto",
         "annonars/clinvar/sv.proto",
+        "annonars/common/versions.proto",
         "annonars/cons/base.proto",
         "annonars/dbsnp/base.proto",
         "annonars/functional/refseq.proto",
@@ -50,6 +51,8 @@ fn main() -> Result<(), anyhow::Error> {
         // Override prost-types with pbjson-types
         .compile_well_known_types()
         .extern_path(".google.protobuf", "::pbjson_types")
+        // Derive the types for utoipa.
+        .message_attribute(".", "#[derive(utoipa::ToSchema)]")
         // Define the protobuf files to compile.
         .compile_protos(&proto_files, &[root])?;
 

protos/annonars/common/versions.proto

@@ -0,0 +1,37 @@
+syntax = "proto3";
+
+package annonars.common.versions;
+
+// Source that data was created from.
+message CreatedFrom {
+    // The name of the data source.
+    string name = 1;
+    // The version of the data source.
+    string version = 2;
+}
+
+// Version specification.
+message VersionSpec {
+    // Identifier of the data.
+    string identifier = 1;
+    // Title of the data.
+    string title = 2;
+    // Creator of the data.
+    string creator = 3;
+    // Contributors of the data.
+    repeated string contributor = 4;
+    // Format of the data.
+    string format = 5;
+    // Date of the data.
+    string date = 6;
+    // Version of the data.
+    string version = 7;
+    // Optional genome release.
+    optional string genome_release = 8;
+    // Data description.
+    string description = 9;
+    // Data source.
+    repeated string source = 10;
+    // Created from information.
+    repeated CreatedFrom created_from = 11;
+}

src/common/cli.rs

@@ -33,6 +33,8 @@ pub enum OutputFormat {
     strum::Display,
     strum::EnumString,
     enum_map::Enum,
+    serde::Serialize,
+    utoipa::ToSchema,
 )]
 #[strum(serialize_all = "lowercase")]
 pub enum GenomeRelease {

src/main.rs

@@ -56,8 +56,8 @@ enum Commands {
     Regions(Regions),
     /// "db-utils" sub commands
     DbUtils(DbUtils),
-    /// "run-server" command.
-    RunServer(server::Args),
+    /// "server" sub command.
+    Server(Server),
 }
 
 /// Parsing of "gene" subcommand
@@ -315,6 +315,23 @@ enum DbUtilsCommands {
     DumpMeta(db_utils::cli::dump_meta::Args),
 }
 
+/// Parsing of "server" subcommands.
+#[derive(Debug, Args, Clone)]
+struct Server {
+    /// The sub command to run.
+    #[command(subcommand)]
+    command: ServerCommands,
+}
+
+/// Enum supporting the parsing of "server *" subcommands.
+#[derive(Debug, Subcommand, Clone)]
+enum ServerCommands {
+    /// "run" sub command.
+    Run(server::run::Args),
+    /// Dump the schema.
+    Schema(crate::server::schema::Args),
+}
+
 pub fn main() -> Result<(), anyhow::Error> {
     let cli = Cli::parse();
 
@@ -417,7 +434,12 @@ pub fn main() -> Result<(), anyhow::Error> {
                     db_utils::cli::dump_meta::run(&cli.common, args)?
                 }
             },
-            Commands::RunServer(args) => server::run(&cli.common, args)?,
+            Commands::Server(args) => match &args.command {
+                ServerCommands::Run(args) => server::run::run(&cli.common, args)?,
+                ServerCommands::Schema(args) => {
+                    server::schema::run(&cli.common, args)?;
+                }
+            },
         }
 
         Ok::<(), Error>(())

src/pbs/common.rs

@@ -0,0 +1,10 @@
+//! Code generate for protobufs by `prost-build`.
+
+/// Information about versions.
+pub mod versions {
+    include!(concat!(env!("OUT_DIR"), "/annonars.common.versions.rs"));
+    include!(concat!(
+        env!("OUT_DIR"),
+        "/annonars.common.versions.serde.rs"
+    ));
+}

src/pbs/mod.rs

@@ -2,6 +2,7 @@
 
 pub mod clinvar;
 pub mod clinvar_data;
+pub mod common;
 pub mod cons;
 pub mod dbsnp;
 pub mod functional;

src/regions/.editorconfig

@@ -0,0 +1,12 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = false
+insert_final_newline = false