Tous nos services doivent disposer d’une interface Swagger UI pour présenter à l’utilisateur leur fichier OpenAPI actuel. Puisque notre backend est entièrement développé en Rust, l’hébergement de cette interface Swagger UI est également assuré via un processus Rust.
Ainsi, pour faire du Swagger UI un citoyen de premier ordre dans l’écosystème Rust, nous avons décidé de reconditionner Swagger-UI en module Rust. De cette façon, dependabot peut détecter les mises à jour du projet sous-jacent et intégrer ces dépendances dans nos projets.
Cela présente aussi l’avantage que dès qu’une mise à jour de cette dépendance est effectuée, nous lançons notre pipeline CI/CD pour vérifier si l’interface utilisateur fonctionne toujours correctement pour nous.
L’interface Swagger UI est empaquetée via GitHub. Déterminer la version actuelle se fait donc par une simple requête à l’API GitHub. De cette manière, nous pouvons décider si une mise à jour est nécessaire ou non. Si une nouvelle version a été publiée, nous téléchargeons les fichiers JS et CSS minifiés et mettons à jour notre dépôt Rust local avec ces nouvelles dépendances.
Après la mise à jour de ces fichiers, nous augmentons également la version du module pour qu’elle corresponde à la version publiée sur GitHub. Ainsi, la version cargo correspond toujours à la version GitHub.
Tout le code nécessaire à cette procédure se trouve dans la définition de l’action GitHub.
L’utilisation de cette crate est assez simple. Les ressources statiques sont exposées sous forme de routes axum et peuvent être fusionnées avec une définition de route existante. Pour implémenter ces routes, vous devez spécifier un préfixe pour les routes ainsi qu’une définition d’API. Cette définition d’API peut être soit un fichier YAML en ligne, soit un lien externe vers la définition de l’API.
Voici un exemple d’utilisation de la crate avec une définition OpenAPI en ligne.
use axum::Router;
use swagger_ui_dist::{ApiDefinition, OpenApiSource};
#[tokio::main]
async fn main() {
let api_def = ApiDefinition {
uri_prefix: "/api",
api_definition: OpenApiSource::Inline(include_str!("petstore.yaml")),
title: Some("My Super Duper API"),
};
let app = Router::new().merge(swagger_ui_dist::generate_routes(api_def));
let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
println!("listening on http://localhost:3000/api");
axum::serve(listener, app).await.unwrap();
}
lien crate.io:
https://crates.io/crates/swagger-ui-dist
repo github:
https://github.com/apimeister/swagger-ui-dist-rs/