✨ add swagger-ui and openapi.yaml (#443)

Signed-off-by: Carlos Feria <[email protected]>

Author: carlosthe19916

Cargo.lock

@@ -13,6 +13,7 @@ members = [
     "server/server",
     "server/cli",
     "server/signature",
+    "server/xtask",
     "server/ui/crate",
 ]
 
@@ -73,6 +74,7 @@ aws-smithy-runtime-api = "1.7"
 async-trait = "0.1"
 env_logger = "0.11"
 utoipa = "5.3"
+utoipa-actix-web = "0.1"
 utoipa-swagger-ui = "9.0"
 actix-web = "4.9"
 actix-web-httpauth = "0.8"

Cargo.toml

@@ -0,0 +1,152 @@
+openapi: 3.1.0
+info:
+  title: Openubl
+  description: Enviar archivos XML a la SUNAT API
+  license:
+    name: Apache License, Version 2.0
+    identifier: Apache-2.0
+  version: 0.1.1
+paths:
+  /api/credentials:
+    get:
+      operationId: list_credentials
+      responses:
+        '200':
+          description: List credentials
+    post:
+      operationId: create_credentials
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/NewCredentialsDto'
+        required: true
+      responses:
+        '200':
+          description: Create credentials
+  /api/credentials/{credentials_id}:
+    get:
+      operationId: get_credentials
+      parameters:
+      - name: credentials_id
+        in: path
+        required: true
+        schema:
+          type: integer
+          format: int32
+      responses:
+        '200':
+          description: Get credential
+    put:
+      operationId: update_credentials
+      parameters:
+      - name: credentials_id
+        in: path
+        required: true
+        schema:
+          type: integer
+          format: int32
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/NewCredentialsDto'
+        required: true
+      responses:
+        '204':
+          description: Update credentials
+    delete:
+      operationId: delete_credentials
+      parameters:
+      - name: credentials_id
+        in: path
+        required: true
+        schema:
+          type: integer
+          format: int32
+      responses:
+        '204':
+          description: Delete credentials
+  /api/documents:
+    get:
+      operationId: list_documents
+      responses:
+        '200':
+          description: List documents
+  /api/documents/{document_id}/download:
+    get:
+      operationId: get_document_file
+      parameters:
+      - name: document_id
+        in: path
+        required: true
+        schema:
+          type: integer
+          format: int32
+      responses:
+        '200':
+          description: Get document's file
+  /api/documents/{document_id}/send:
+    post:
+      operationId: send_document
+      parameters:
+      - name: document_id
+        in: path
+        required: true
+        schema:
+          type: integer
+          format: int32
+      responses:
+        '200':
+          description: Get document's file
+  /q/health/live:
+    get:
+      operationId: liveness
+      responses:
+        '200':
+          description: Liveness
+  /q/health/read:
+    get:
+      operationId: readiness
+      responses:
+        '200':
+          description: Readiness
+components:
+  schemas:
+    NewCredentialsDto:
+      type: object
+      required:
+      - name
+      - username_sol
+      - password_sol
+      - client_id
+      - client_secret
+      - url_invoice
+      - url_despatch
+      - url_perception_retention
+      - supplier_ids_applied_to
+      properties:
+        client_id:
+          type: string
+        client_secret:
+          type: string
+        description:
+          type:
+          - string
+          - 'null'
+        name:
+          type: string
+        password_sol:
+          type: string
+        supplier_ids_applied_to:
+          type: array
+          items:
+            type: string
+        url_despatch:
+          type: string
+        url_invoice:
+          type: string
+        url_perception_retention:
+          type: string
+        username_sol:
+          type: string

openapi.yaml

@@ -26,7 +26,8 @@ clap = { workspace = true, features = ["derive", "env"] }
 anyhow = { workspace = true }
 env_logger = { workspace = true }
 thiserror = { workspace = true }
-utoipa = { workspace = true, features = ["actix_extras"] }
+utoipa = { workspace = true, features = ["actix_extras", "yaml"] }
+utoipa-actix-web = { workspace = true }
 utoipa-swagger-ui = { workspace = true, features = ["actix-web"] }
 actix-web-httpauth = { workspace = true }
 actix-4-jwt-auth = { workspace = true }

server/server/Cargo.toml

@@ -2,7 +2,7 @@ use openubl_entity as entity;
 use serde::{Deserialize, Serialize};
 use utoipa::ToSchema;
 
-#[derive(Serialize, Deserialize)]
+#[derive(Serialize, Deserialize, ToSchema)]
 pub struct DocumentDto {
     pub id: i32,
     pub supplier_id: String,

server/server/src/dto.rs

@@ -7,9 +7,13 @@ use actix_multipart::form::tempfile::TempFileConfig;
 use actix_web::middleware::Logger;
 use actix_web::{web, App, HttpServer};
 
+use openapi::ApiDoc;
 use openubl_api::system::InnerSystem;
 use openubl_common::config::Database;
 use openubl_storage::StorageSystem;
+use utoipa::OpenApi;
+use utoipa_actix_web::AppExt;
+use utoipa_swagger_ui::SwaggerUi;
 
 use crate::server::credentials::{
     create_credentials, delete_credentials, get_credentials, list_credentials, update_credentials,
@@ -20,6 +24,7 @@ use actix_web_static_files::{deps::static_files::Resource, ResourceFiles};
 use openubl_ui::{openubl_ui, UI};
 
 mod dto;
+pub mod openapi;
 pub mod server;
 
 pub struct UiResources {
@@ -89,11 +94,25 @@ impl ServerRun {
         let app_state = Arc::new(AppState { system, storage });
 
         HttpServer::new(move || {
-            App::new()
-                .app_data(web::Data::from(app_state.clone()))
+            let (app, api) = App::new()
                 .wrap(Logger::default())
+                .into_utoipa_app()
+                //
+                .openapi(ApiDoc::openapi())
+                //
+                .app_data(web::Data::from(app_state.clone()))
                 .app_data(TempFileConfig::default())
-                .configure(configure)
+                // q
+                .service(utoipa_actix_web::scope("/q").configure(configure_q))
+                // API
+                .service(utoipa_actix_web::scope("/api").configure(configure_api))
+                .split_for_parts();
+
+            app
+                // Swagger
+                .service(SwaggerUi::new("/swagger-ui/{_:.*}").url("/openapi.json", api))
+                .service(web::redirect("/swagger-ui", "/swagger-ui/"))
+                // UI
                 .service(ResourceFiles::new("/", ui.resources()).resolve_not_found_to(""))
         })
         .bind(self.bind_addr)?
@@ -109,11 +128,13 @@ pub struct AppState {
     pub storage: StorageSystem,
 }
 
-pub fn configure(config: &mut web::ServiceConfig) {
+pub fn configure_q(config: &mut utoipa_actix_web::service_config::ServiceConfig) {
     // Health
     config.service(health::liveness);
     config.service(health::readiness);
+}
 
+pub fn configure_api(config: &mut utoipa_actix_web::service_config::ServiceConfig) {
     // Documents
     config.service(list_documents);
     config.service(get_document_file);

server/server/src/lib.rs

@@ -0,0 +1,35 @@
+use actix_web::App;
+use utoipa::{
+    openapi::{Info, License},
+    OpenApi,
+};
+use utoipa_actix_web::AppExt;
+
+use crate::{configure_api, configure_q};
+
+#[derive(OpenApi)]
+#[openapi()]
+pub struct ApiDoc;
+
+pub fn default_openapi_info() -> Info {
+    let mut info = Info::new("Openubl", env!("CARGO_PKG_VERSION"));
+    info.description = Some("Enviar archivos XML a la SUNAT API".into());
+    info.license = {
+        let mut license = License::new("Apache License, Version 2.0");
+        license.identifier = Some("Apache-2.0".into());
+        Some(license)
+    };
+    info
+}
+
+pub async fn create_openapi() -> anyhow::Result<utoipa::openapi::OpenApi> {
+    let (_, mut openapi) = App::new()
+        .into_utoipa_app()
+        .service(utoipa_actix_web::scope("/q").configure(configure_q))
+        .service(utoipa_actix_web::scope("/api").configure(configure_api))
+        .split_for_parts();
+
+    openapi.info = default_openapi_info();
+
+    Ok(openapi)
+}

server/server/src/openapi.rs

@@ -0,0 +1,18 @@
+[package]
+name = "openubl-xtask"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+
+[[bin]]
+name = "xtask"
+path = "src/main.rs"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+openubl-server = { workspace = true }
+
+anyhow = { workspace = true }
+clap = { workspace = true, features = ["derive", "env"] }
+tokio = { workspace = true, features = ["full"] }