From d1556200b712f5751680d45c947d68e0ebf29e41 Mon Sep 17 00:00:00 2001 From: Manuel Holtgrewe Date: Thu, 21 Nov 2024 09:15:21 +0100 Subject: [PATCH] fix: OpenAPI for /api/v1/genes/transcripts (#628) (#629) --- openapi.schema.yaml | 230 +++++++++++++++++++++++- src/server/run/actix_server/gene_txs.rs | 19 +- src/server/run/mod.rs | 16 +- 3 files changed, 254 insertions(+), 11 deletions(-) diff --git a/openapi.schema.yaml b/openapi.schema.yaml index e63df609..e082f08a 100644 --- a/openapi.schema.yaml +++ b/openapi.schema.yaml @@ -7,8 +7,55 @@ info: email: manuel.holtgrewe@bih-charite.de license: name: MIT - version: 0.29.6 + version: 0.30.0 paths: + /api/v1/genes/transcripts: + get: + tags: + - gene_txs + summary: Query for transcripts of a gene. + operationId: genesTranscriptsList + parameters: + - name: hgnc_id + in: query + description: HGNC gene ID. + required: true + schema: + type: string + - name: genome_build + in: query + description: Genome build. + required: true + schema: + $ref: '#/components/schemas/Assembly' + - name: page_size + in: query + description: Page size. + required: false + schema: + type: integer + format: int32 + nullable: true + - name: next_page_token + in: query + description: Next page token. + required: false + schema: + type: string + nullable: true + responses: + '200': + description: Transcripts for the selected gene. + content: + application/json: + schema: + $ref: '#/components/schemas/GenesTranscriptsListResponse' + '500': + description: Internal server error. + content: + application/json: + schema: + $ref: '#/components/schemas/CustomError' /api/v1/seqvars/csq: get: tags: @@ -224,6 +271,40 @@ components: version_cdot: type: string description: Version of cdot used. + ExonAlignment: + type: object + description: Store the alignment of one exon to the reference. + required: + - alt_start_i + - alt_end_i + - ord + - cigar + properties: + alt_start_i: + type: integer + format: int32 + description: Start position on reference. + alt_end_i: + type: integer + format: int32 + description: End position on reference. + ord: + type: integer + format: int32 + description: Exon number. + alt_cds_start_i: + type: integer + format: int32 + description: CDS start coordinate. + nullable: true + alt_cds_end_i: + type: integer + format: int32 + description: CDS end coordinate. + nullable: true + cigar: + type: string + description: CIGAR string of alignment, empty indicates full matches. FeatureBiotype: type: string description: Encode feature biotype. @@ -257,6 +338,73 @@ components: value: type: string description: Enum for `AnnField::feature_type`. + GenesTranscriptsListQuery: + type: object + description: Query arguments for the `/api/v1/genes/transcripts` endpoint. + required: + - hgnc_id + - genome_build + properties: + hgnc_id: + type: string + description: HGNC gene ID. + genome_build: + $ref: '#/components/schemas/Assembly' + page_size: + type: integer + format: int32 + description: Page size. + nullable: true + next_page_token: + type: string + description: Next page token. + nullable: true + GenesTranscriptsListResponse: + type: object + description: Response of the `/api/v1/genes/transcripts` endpoint. + required: + - transcripts + properties: + transcripts: + type: array + items: + $ref: '#/components/schemas/Transcript' + description: The transcripts for the gene. + next_page_token: + type: string + description: The token to continue from a previous query. + nullable: true + GenomeAlignment: + type: object + description: Store information about a transcript aligning to a genome. + required: + - genome_build + - contig + - strand + - exons + properties: + genome_build: + $ref: '#/components/schemas/Assembly' + contig: + type: string + description: Accession of the contig sequence. + cds_start: + type: integer + format: int32 + description: CDS end position, `-1` to indicate `None`. + nullable: true + cds_end: + type: integer + format: int32 + description: CDS end position, `-1` to indicate `None`. + nullable: true + strand: + $ref: '#/components/schemas/Strand' + exons: + type: array + items: + $ref: '#/components/schemas/ExonAlignment' + description: Exons of the alignment. GenomeRelease: type: string description: Select the genome release to use. @@ -449,6 +597,13 @@ components: hgvs_rs: type: string description: Version of the `hgvs` crate. + Strand: + type: string + description: Enumeration for the two strands of the genome. + enum: + - unknown + - plus + - minus StrucvarsCsqQuery: type: object description: Query parameters of the `/api/v1/strucvars/csq` endpoint. @@ -526,6 +681,79 @@ components: - upstream_variant - downstream_variant - intergenic_variant + Transcript: + type: object + description: Transcript information. + required: + - id + - gene_symbol + - gene_id + - biotype + - tags + - genome_alignments + properties: + id: + type: string + description: Transcript accession with version, e.g., `"NM_007294.3"` or `"ENST00000461574.1"` for BRCA1. + gene_symbol: + type: string + description: HGNC symbol, e.g., `"BRCA1"` + gene_id: + type: string + description: HGNC gene identifier, e.g., `"1100"` for BRCA1. + biotype: + $ref: '#/components/schemas/TranscriptBiotype' + tags: + type: array + items: + $ref: '#/components/schemas/TranscriptTag' + description: Transcript flags. + protein: + type: string + description: Identifier of the corresponding protein. + nullable: true + start_codon: + type: integer + format: int32 + description: CDS start codon. + nullable: true + stop_codon: + type: integer + format: int32 + description: CDS stop codon. + nullable: true + genome_alignments: + type: array + items: + $ref: '#/components/schemas/GenomeAlignment' + description: Alignments on the different genome builds. + filtered: + type: boolean + description: Whether this transcript has an issue (e.g. MissingStopCodon), cf. `mehari::db::create::mod::Reason`. + nullable: true + filter_reason: + type: integer + format: int32 + description: Reason for filtering. + nullable: true + minimum: 0 + TranscriptBiotype: + type: string + description: Enumeration for `Transcript::biotype`. + enum: + - coding + - non_coding + TranscriptTag: + type: string + enum: + - basic + - ensembl_canonical + - mane_select + - mane_plus_clinical + - ref_seq_select + - selenoprotein + - gencode_primary + - other VersionsInfoResponse: type: object description: Response of the `/api/v1/version` endpoint. diff --git a/src/server/run/actix_server/gene_txs.rs b/src/server/run/actix_server/gene_txs.rs index 0fd13f81..66b2fd34 100644 --- a/src/server/run/actix_server/gene_txs.rs +++ b/src/server/run/actix_server/gene_txs.rs @@ -87,8 +87,8 @@ async fn handle( } /// Query arguments for the `/api/v1/genes/transcripts` endpoint. -#[derive(Debug, Clone, serde::Deserialize, utoipa::ToSchema)] -struct GenesTranscriptsListQuery { +#[derive(Debug, Clone, serde::Deserialize, utoipa::ToSchema, utoipa::IntoParams)] +pub(crate) struct GenesTranscriptsListQuery { /// HGNC gene ID. pub hgnc_id: String, /// Genome build. @@ -113,7 +113,7 @@ impl From for pbs::server::GeneTranscriptsQuery { /// Enumeration for `Transcript::biotype`. #[derive(Debug, Clone, serde::Serialize, utoipa::ToSchema)] #[serde(rename_all = "snake_case")] -enum TranscriptBiotype { +pub(crate) enum TranscriptBiotype { /// Coding transcript. Coding, /// Non-coding transcript. @@ -135,7 +135,7 @@ impl TryFrom for TranscriptBiotype { // Bit values for the transcript tags. #[derive(Debug, Clone, serde::Serialize, utoipa::ToSchema)] #[serde(rename_all = "snake_case")] -enum TranscriptTag { +pub(crate) enum TranscriptTag { /// Member of Ensembl basic. Basic, /// Member of Ensembl canonical. @@ -175,7 +175,7 @@ impl TryFrom for TranscriptTag { /// Enumeration for the two strands of the genome. #[derive(Debug, Clone, serde::Serialize, utoipa::ToSchema)] #[serde(rename_all = "snake_case")] -enum Strand { +pub(crate) enum Strand { /// unknown Unknown, /// Forward / plus @@ -196,7 +196,7 @@ impl From for Strand { /// Store the alignment of one exon to the reference. #[derive(Debug, Clone, serde::Serialize, utoipa::ToSchema)] -struct ExonAlignment { +pub(crate) struct ExonAlignment { /// Start position on reference. pub alt_start_i: i32, /// End position on reference. @@ -226,7 +226,7 @@ impl From for ExonAlignment { /// Store information about a transcript aligning to a genome. #[derive(Debug, Clone, serde::Serialize, utoipa::ToSchema)] -struct GenomeAlignment { +pub(crate) struct GenomeAlignment { /// The genome build identifier. pub genome_build: Assembly, /// Accession of the contig sequence. @@ -258,7 +258,7 @@ impl TryFrom for GenomeAlignment { /// Transcript information. #[derive(Debug, Clone, serde::Serialize, utoipa::ToSchema)] -struct Transcript { +pub(crate) struct Transcript { /// Transcript accession with version, e.g., `"NM_007294.3"` or `"ENST00000461574.1"` for BRCA1. pub id: String, /// HGNC symbol, e.g., `"BRCA1"` @@ -317,7 +317,7 @@ impl TryFrom for Transcript { /// Response of the `/api/v1/genes/transcripts` endpoint. #[derive(Debug, Clone, serde::Serialize, utoipa::ToSchema)] -struct GenesTranscriptsListResponse { +pub(crate) struct GenesTranscriptsListResponse { /// The transcripts for the gene. pub transcripts: Vec, /// The token to continue from a previous query. @@ -344,6 +344,7 @@ impl TryFrom for GenesTranscriptsListRespo #[utoipa::path( get, operation_id = "genesTranscriptsList", + params(GenesTranscriptsListQuery), responses( (status = 200, description = "Transcripts for the selected gene.", body = GenesTranscriptsListResponse), (status = 500, description = "Internal server error.", body = CustomError) diff --git a/src/server/run/mod.rs b/src/server/run/mod.rs index dc5ccbd0..6e0dadc6 100644 --- a/src/server/run/mod.rs +++ b/src/server/run/mod.rs @@ -24,6 +24,10 @@ pub mod openapi { StrucvarsGeneTranscriptEffects, StrucvarsTranscriptEffect, }; use crate::common::GenomeRelease; + use crate::server::run::actix_server::gene_txs::{ + ExonAlignment, GenesTranscriptsListQuery, GenesTranscriptsListResponse, GenomeAlignment, + Strand, Transcript, TranscriptBiotype, TranscriptTag, + }; use crate::server::run::actix_server::seqvars_csq::{ SeqvarsCsqQuery, SeqvarsCsqResponse, SeqvarsCsqResultEntry, }; @@ -34,14 +38,16 @@ pub mod openapi { Assembly, DataVersionEntry, SoftwareVersions, VersionsInfoResponse, }; - use super::actix_server::{seqvars_csq, strucvars_csq, versions, CustomError}; + use super::actix_server::{gene_txs, seqvars_csq, strucvars_csq, versions, CustomError}; /// Utoipa-based `OpenAPI` generation helper. #[derive(utoipa::OpenApi)] #[openapi( paths( versions::handle, + gene_txs::handle_with_openapi, seqvars_csq::handle_with_openapi, + strucvars_csq::handle_with_openapi, strucvars_csq::handle_with_openapi ), components(schemas( @@ -67,6 +73,14 @@ pub mod openapi { Pos, Message, SoFeature, + ExonAlignment, + GenesTranscriptsListQuery, + GenesTranscriptsListResponse, + GenomeAlignment, + Strand, + Transcript, + TranscriptBiotype, + TranscriptTag, )) )] pub struct ApiDoc;