Rebase on upstream (#6)

* chore: remove travis in preparation for GHA * ci: added github-actions * ci: added linters Currently both clippy and rustfmt are running on nightly. Also the corresponding suggestions recommended by clippy has been applied. * feat(skip): add support for serde skip Skips fields if the serde skip attribute is found. * chore: make linter workflow lowercase to match cicd * Update version Paperclip version 0.5 causes problems with Actix 3 * remove **experimental** * remove nightly * properties with a leading '@' should be renamed to 'at_' to allow both variants (e.g. @type and type) at the same time (paperclip-rs#344) * enums variants: replace dots (.) with underscore (_) * properties with a leading '@' should be renamed to 'at_' to allow both variants (e.g. @type and type) at the same time * replace '@' also for Builders (generics) * harmonize to_snek_case to deal with unwanted characters (like @) * support boxed values in Builder impl * to_snek_case -> to_snake_case Co-authored-by: Jens Gersdorf <[email protected]> * feat: expose openapi v3 spec (paperclip-rs#311) Expose openapi v3 spec through `with_json_spec_v3_at` and `with_raw_json_spec_v3`; this is done through a conversion from the v2 types to v3 and so all existing code should be valid. It also means that we're not yet exposing any specific v3 features. * feat(error responses): error responses definitions (paperclip-rs#307) * feat(error responses): error responses definitions Ability to specify an error type schema to an error response, either to each specific error code or a common for all. * feat(error responses): error overlay type Add error overlay over an existing Apiv2Error which allows us to filter out errors from the existing type which may not suit a particular URI handler. * Update cicd.yml (paperclip-rs#345) Add missing v3 feature test * fix: add missing Configure app_data and trim paths (paperclip-rs#312) Trimming the base path is useful when using scopes otherwise you could get the base uri repeated, eg: "/v0/v0". Obviously this depends on the use case so call only if you want this. * Upgrade to GitHub-native Dependabot (paperclip-rs#319) Co-authored-by: dependabot-preview[bot] <27856297+dependabot-preview[bot]@users.noreply.github.com> Co-authored-by: Tiago Castro <[email protected]> * Update strum_macros requirement from 0.19 to 0.22 (paperclip-rs#348) Updates the requirements on [strum_macros](https://github.com/Peternator7/strum) to permit the latest version. - [Release notes](https://github.com/Peternator7/strum/releases) - [Changelog](https://github.com/Peternator7/strum/blob/master/CHANGELOG.md) - [Commits](https://github.com/Peternator7/strum/commits) --- updated-dependencies: - dependency-name: strum_macros dependency-type: direct:production ... Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * chore: update strum requirement from 0.19 to 0.22 (paperclip-rs#347) Updates the requirements on [strum](https://github.com/Peternator7/strum) to permit the latest version. - [Release notes](https://github.com/Peternator7/strum/releases) - [Changelog](https://github.com/Peternator7/strum/blob/master/CHANGELOG.md) - [Commits](https://github.com/Peternator7/strum/commits) --- updated-dependencies: - dependency-name: strum dependency-type: direct:production ... Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Tiago Castro <[email protected]> * feat: add Url feature (paperclip-rs#334) * Add Url feature Allow the usage of the Url object on the API * CHANGELOG: Add url type support Signed-off-by: Patrick José Pereira <[email protected]> * swagger-ui: Add feature (paperclip-rs#331) * plugins: Add swagger-ui submodule Signed-off-by: Patrick José Pereira <[email protected]> * Add swagger-ui feature Signed-off-by: Patrick José Pereira <[email protected]> * tests: Update test_app to include swagger-ui test Signed-off-by: Patrick José Pereira <[email protected]> * Makefile: Add swagger-ui on test Signed-off-by: Patrick José Pereira <[email protected]> * github: cicd: Add swagger-ui on test Signed-off-by: Patrick José Pereira <[email protected]> * CHANGELOG: Add swagger-ui feature Signed-off-by: Patrick José Pereira <[email protected]> * github: Init submodules before building Signed-off-by: Patrick José Pereira <[email protected]> * chore: prepare release of version 0.6 (paperclip-rs#349) * chore: several fixes (paperclip-rs#350) * fix: add missing codegen feature in v2 comments * fix: remove unused and gate features * fix: resolve actix2 compilation errors * chore: run actix2 tests on CI * chore: prepare release of version 0.6.1 (paperclip-rs#351) * fix(paperclip-actix): add symlink to swagger-ui This way it will be uploaded to crates.io * chore: release 0.4.2 of the paperclip-actix plugin * Update actix plugin tutorial to mention v3 and macro syntax (paperclip-rs#354) * Fix favicons for swagger-ui and add simple error handling (paperclip-rs#369) Added error message for getting files from swagger-ui/dist. Fixed favicons making panic on unwrap since contents_utf8 doesn't work on images. * Supports `actix-web` `4.0.0-beta.4`. (#1) * Fix issues for upgrading `actix-web` to `4.0.0-beta.12`. (#4) * Update for `actix4`. * Delete useless export. Co-authored-by: Tiago Castro <[email protected]> Co-authored-by: Ankur Srivastava <[email protected]> Co-authored-by: Sleepybæ <[email protected]> Co-authored-by: jens1205 <[email protected]> Co-authored-by: Jens Gersdorf <[email protected]> Co-authored-by: dependabot-preview[bot] <27856297+dependabot-preview[bot]@users.noreply.github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Patrick José Pereira <[email protected]> Co-authored-by: Dylan Anthony <[email protected]> Co-authored-by: Bilel Medimegh <[email protected]>
fluidex · Dec 13, 2021 · f0fa21e · f0fa21e
1 parent 0679e49
commit f0fa21e
Show file tree

Hide file tree

Showing 50 changed files with 2,309 additions and 303 deletions.
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -0,0 +1,15 @@
+version: 2
+updates:
+- package-ecosystem: cargo
+  directory: "/"
+  schedule:
+    interval: daily
+    time: "23:30"
+  open-pull-requests-limit: 10
+  ignore:
+  - dependency-name: actix-http
+    versions:
+    - ">= 2.a, < 3"
+  - dependency-name: actix-web
+    versions:
+    - ">= 3.a, < 4"
diff --git a/.github/workflows/cicd.yml b/.github/workflows/cicd.yml
@@ -0,0 +1,95 @@
+name: cicd
+
+on:
+  pull_request:
+  schedule:
+    - cron: "0 7 * * *"
+
+jobs:
+  build_and_test:
+    strategy:
+      fail-fast: false
+      matrix:
+        version:
+          - stable
+          - nightly
+
+    name: ${{ matrix.version }} - x86_64-unknown-linux-gnu
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Install ${{ matrix.version }}
+        uses: actions-rs/toolchain@v1
+        with:
+          toolchain: ${{ matrix.version }}-x86_64-unknown-linux-gnu
+          profile: minimal
+          override: true
+
+      - name: Generate Cargo.lock
+        uses: actions-rs/cargo@v1
+        with:
+          command: generate-lockfile
+
+      - name: Cache cargo registry
+        uses: actions/cache@v1
+        with:
+          path: ~/.cargo/registry
+          key: ${{ matrix.version }}-x86_64-unknown-linux-gnu-cargo-registry-trimmed-${{ hashFiles('**/Cargo.lock') }}
+
+      - name: Cache cargo index
+        uses: actions/cache@v1
+        with:
+          path: ~/.cargo/git
+          key: ${{ matrix.version }}-x86_64-unknown-linux-gnu-cargo-index-trimmed-${{ hashFiles('**/Cargo.lock') }}
+
+      - name: Cache cargo build
+        uses: actions/cache@v1
+        with:
+          path: target
+          key: ${{ matrix.version }}-x86_64-unknown-linux-gnu-cargo-build-trimmed-${{ hashFiles('**/Cargo.lock') }}
+
+      - name: Init submodule
+        run: |
+          git submodule update --init --recursive
+
+      - name: Build actix features
+        uses: actions-rs/cargo@v1
+        timeout-minutes: 10
+        with:
+          command: build
+          args: --all --features "actix cli chrono url uuid swagger-ui v3"
+
+      - name: Build actix2 features
+        uses: actions-rs/cargo@v1
+        timeout-minutes: 10
+        with:
+          command: build
+          args: --all --features "actix2 cli chrono url uuid swagger-ui v3"
+
+      - name: Run actix tests
+        uses: actions-rs/cargo@v1
+        timeout-minutes: 20
+        with:
+          command: test
+          args: --all --features "actix cli chrono url uuid swagger-ui v3"
+
+      - name: Run actix2 tests
+        uses: actions-rs/cargo@v1
+        timeout-minutes: 20
+        with:
+          command: test
+          args: --all --features "actix2 cli chrono url uuid swagger-ui v3"
+
+      - name: Run tests
+        timeout-minutes: 40
+        run: make test
+
+      - name: Install cargo-cache
+        continue-on-error: true
+        run: |
+          cargo install cargo-cache --no-default-features --features ci-autoclean
+
+      - name: Run the cargo cache
+        run: |
+          cargo-cache
diff --git a/.github/workflows/linter.yml b/.github/workflows/linter.yml
@@ -0,0 +1,45 @@
+name: linter
+on:
+  pull_request:
+  schedule:
+    - cron: "0 7 * * *"
+
+jobs:
+  clippy:
+    name: clippy
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        rust:
+          - nightly
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions-rs/toolchain@v1
+        with:
+          components: clippy
+          toolchain: ${{ matrix.rust }}
+          override: true
+      - uses: actions-rs/clippy-check@v1
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          args: --all --features "actix" -- -D clippy::all
+
+  fmt:
+    name: rustfmt
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        rust:
+          - nightly
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions-rs/toolchain@v1
+        with:
+          components: rustfmt
+          toolchain: ${{ matrix.rust }}
+          override: true
+      - uses: actions-rs/cargo@v1
+        with:
+          toolchain: ${{ matrix.rust }}
+          command: fmt
+          args: --all -- --check
diff --git a/.gitmodules b/.gitmodules
@@ -0,0 +1,3 @@
+[submodule "plugins/swagger-ui"]
+	path = plugins/swagger-ui
+	url = https://github.com/swagger-api/swagger-ui
diff --git a/.travis.yml b/.travis.yml
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,12 +4,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.6.1] - 2021-10-15
+### Fixed
+- Actix2 plugin: fix compilation error `ReqData` not found
+
+## [0.6.0] - 2021-10-13
 ### Added
 - Add support for actix-web-macros methods routing [PR#289](https://github.com/wafflespeanut/paperclip/pull/289)
 - Actix plugin: add an empty impl for actix-web `ReqData<T>`
+- Add support for the `#[serde(skip)]` attribute in structs and enums.
+- Expose openapi v3 spec through `with_json_spec_v3_at` and `with_raw_json_spec_v3` - this is done through a conversion from
+ the v2 types to v3 and so all existing code should be valid. It also means that we're not yet exposing any specific
+ v3 features.
+- Added new method `trim_base_path` to trim the api base path from all method paths.
+- `Apiv2Schema` supports `url` [PR#334](https://github.com/paperclip-rs/paperclip/pull/334)
+- Add [swagger-ui](https://swagger.io/tools/swagger-ui/) for visualization/test of API via `with_swagger_ui_at` [PR#331](https://github.com/paperclip-rs/paperclip/pull/331).
 
 ### Changed
+- Actix plugin: `#[api_v2_errors]` macro now supports adding different error schemes per response code.
+- Actix plugin: Add new `#[api_v2_errors_overlay]` macro which can be used to filter out unwanted responses from an existing error type.
 
 ### Fixed
 - Optional type aliases like `type Email = Option<String>` will not be added to the `required` fields.

diff --git a/Cargo.toml b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "paperclip"
-version = "0.5.0"
+version = "0.6.1"
 authors = ["Ravi Shankar <[email protected]>"]
 edition = "2018"
 description = "OpenAPI tooling library for type-safe compile-time checked HTTP APIs"
@@ -18,15 +18,16 @@ path = "src/bin/main.rs"
 required-features = ["cli"]
 
 [dependencies]
+paperclip-actix = { path = "plugins/actix-web", version = "0.4.2", optional = true }
+paperclip-core = { path = "core", version = "0.4.1" }
+paperclip-macros = { path = "macros", version = "0.5.1", optional = true }
+
 env_logger = { version = "0.8", optional = true }
 git2 = { version = "0.13", optional = true }
 heck = { version = "0.3", optional = true }
 http = { version = "0.2", optional = true }
 itertools = "0.10"
 log = { version = "0.4", optional = true }
-paperclip-actix = { path = "plugins/actix-web", version = "0.3.0", optional = true }
-paperclip-core = { path = "core", version = "0.3.0" }
-paperclip-macros = { path = "macros", version = "0.4.0", optional = true }
 parking_lot = { version = ">=0.10,<0.12" }
 regex = { version = "1.3", optional = true }
 reqwest = { version = "0.10", features = ["blocking"], optional = true }
@@ -37,10 +38,12 @@ serde_json = "1.0"
 serde_yaml = "0.8"
 structopt = { version = "0.3", optional = true }
 tinytemplate = { version = "1.1", optional = true }
-url = ">=1.7,<3"
+url_dep = { version = ">=1.7,<3", package = "url" }
 thiserror = "1.0"
 anyhow = "1.0"
 once_cell = "1.4"
+openapiv3 = { version = "0.4.0", optional = true }
+indexmap = { version = "1.0", features = ["serde-1", "std"], optional = true }
 
 [dev-dependencies]
 actix-service = "2.0.0-beta.4"
@@ -64,18 +67,23 @@ actix2 = ["actix-base", "paperclip-actix/actix2"]
 actix3 = ["actix-base", "paperclip-actix/actix3"]
 actix4 = ["actix-base", "paperclip-actix/actix4"]
 actix-base = ["v2", "paperclip-macros/actix"]
+swagger-ui = ["paperclip-actix/swagger-ui"]
 
 # OpenAPI support (v2 and codegen)
 cli = ["env_logger", "structopt", "git2", "v2", "codegen"]
 codegen = ["heck", "http", "log", "regex", "tinytemplate", "paperclip-core/codegen"]
 v2 = ["paperclip-macros/v2", "paperclip-core/v2"]
+# OpenAPI v2 to v3 support
+v3 = ["openapiv3", "indexmap", "v2", "paperclip-core/v3", "paperclip-actix/v3"]
+
 
 # Features for implementing traits for dependencies.
 actix-multipart = ["paperclip-core/actix-multipart"]
 actix-session = ["paperclip-core/actix-session"]
 actix-files = ["paperclip-core/actix-files"]
 chrono = ["paperclip-core/chrono"]
 rust_decimal = ["paperclip-core/rust_decimal"]
+url = ["paperclip-core/url"]
 uuid = ["paperclip-core/uuid"]
 serde_qs = ["paperclip-core/serde_qs"]
 

diff --git a/Makefile b/Makefile
@@ -30,7 +30,7 @@ build:
 	cargo build --features cli
 
 test:
-	cargo test --all --features "actix cli chrono uuid"
+	cargo test --all --features "actix cli chrono uuid swagger-ui"
 	# Compile the code generated through tests.
 	cd tests/test_pet && cargo check
 	cd tests/test_pet/cli && CARGO_TARGET_DIR=../target cargo check

diff --git a/book/actix-plugin.md b/book/actix-plugin.md
@@ -1,6 +1,6 @@
-# Host OpenAPI v2 spec through actix-web
+# Host OpenAPI spec through actix-web
 
-With `actix` feature enabled, paperclip exports an **experimental** plugin for [actix-web](https://github.com/actix/actix-web) framework to host OpenAPI v2 spec for your APIs *automatically*. While it's not feature complete, you can rely on it to not break your actix-web flow.
+With `actix` feature enabled, paperclip exports a plugin for [actix-web](https://github.com/actix/actix-web) framework to host OpenAPI v2 spec for your APIs *automatically*. While it's not feature complete, you can rely on it to not break your actix-web flow.
 
 Let's start with a simple actix-web application. It has `actix-web` and `serde` for JSON'ifying your APIs. Let's also add `paperclip` with `actix` feature.
 
@@ -14,7 +14,8 @@ actix-web = "3.0"
 # this plugin works smoothly with the nightly compiler, it also works in stable
 # channel (replace "actix-nightly" feature with "actix" in that case). There maybe compilation errors,
 # but those can be fixed.
-paperclip = { version = "0.4", features = ["actix-nightly"] }
+# Add the "v3" option if you want to expose an OpenAPI v3 document
+paperclip = { version = "0.6", features = ["actix"] }
 serde = "1.0"
 ```
 
@@ -53,6 +54,8 @@ use actix_web::{App, HttpServer};
 use paperclip::actix::{
     // extension trait for actix_web::App and proc-macro attributes
     OpenApiExt, Apiv2Schema, api_v2_operation,
+    // If you prefer the macro syntax for defining routes, import the paperclip macros
+    // get, post, put, delete
     // use this instead of actix_web::web
     web::{self, Json},
 };
@@ -67,6 +70,8 @@ struct Pet {
 
 // Mark operations like so...
 #[api_v2_operation]
+// Add the next line if you want to use the macro syntax
+// #[post("/pets")]
 async fn echo_pet(body: Json<Pet>) -> Result<Json<Pet>, ()> {
     Ok(body)
 }
@@ -81,8 +86,11 @@ async fn main() -> std::io::Result<()> {
             web::resource("/pets")
                 .route(web::post().to(echo_pet))
         )
-        // Mount the JSON spec at this path.
-        .with_json_spec_at("/api/spec")
+        // Or just .service(echo_pet) if you're using the macro syntax
+        // Mount the v2/Swagger JSON spec at this path.
+        .with_json_spec_at("/api/spec/v2")
+        // If you added the "v3" feature, you can also include
+        // .with_json_spec_v3_at("/api/spec/v3")
 
         // ... or if you wish to build the spec by yourself...
 
@@ -105,7 +113,8 @@ We have:
  - Switched from `actix_web::web` to `paperclip::actix::web`.
  - Marked our `Pet` struct and `add_pet` function as OpenAPI-compatible schema and operation using proc macro attributes.
  - Transformed our `actix_web::App` to a wrapper using `.wrap_api()`.
- - Mounted the JSON spec at a relative path using `.with_json_spec_at("/api/spec")`.
+ - Optionally switched to Paperclip's macros instead of the actix-web route macros
+ - Mounted the JSON spec at a relative path using `.with_json_spec_at("/api/spec/v2")` (and optionally a v3 spec as well).
  - Built (using `.build()`) and passed the original `App` back to actix-web.
 
 Note that we never touched the service, resources, routes or anything else! This means that our original actix-web flow is unchanged.
@@ -119,7 +128,7 @@ curl -X POST http://localhost:8080/pets -H "Content-Type: application/json" -d '
 And see the specs with this:
 
 ```
-curl http://localhost:8080/api/spec
+curl http://localhost:8080/api/spec/v2
 ```
 
 ... we get the swagger spec as a JSON!