Merge pull request #2 from pachecoio/feature/example-query

Feature/example query

CONTRIBUTING.md

@@ -0,0 +1,71 @@
+## CONTRIBUTING.md
+
+### Welcome to the OpenAPI Mocker Contributing Guide!
+
+Thank you for your interest in contributing to the OpenAPI Mocker project! We're glad you're here. This document provides guidelines for making contributions to the project. Whether you're looking to submit a bug report, propose new features, or contribute code, your help is very much appreciated.
+
+### How to Contribute
+
+#### Reporting Bugs
+
+Bugs are tracked as GitHub issues. To report a bug, create an issue and include:
+
+- A clear title and description.
+- Steps to reproduce.
+- Expected behavior.
+- Actual behavior.
+- Screenshots if applicable.
+
+#### Suggesting Enhancements
+
+We love to receive suggestions for improvements! If you have ideas to make OpenAPI Mocker better, please submit an issue with the following:
+
+- A clear title and description.
+- Explain why this enhancement would be useful to most OpenAPI Mocker users.
+- Provide a step-by-step description of the suggested enhancement in as much detail as possible.
+
+#### Your First Code Contribution
+
+Unsure where to begin contributing? You can start by looking through the 'beginner' and 'help-wanted' issues:
+
+- **Beginner issues** - issues which should only require a few lines of code, and a test or two.
+- **Help wanted issues** - issues which should be a bit more involved than beginner issues.
+
+Both issue lists are great places to start and are specifically tagged to indicate that help is needed.
+
+#### Pull Requests
+
+Here’s how to submit a pull request:
+
+1. Fork the repo and create your branch from `main`.
+2. Clone the repository to your local machine.
+3. Make your changes and ensure your code adheres to the existing style to keep the code consistent.
+4. If you've added code, add tests!
+5. Ensure your code passes all the tests.
+6. Issue that pull request!
+
+Include a clear description of the reasons for your changes. It should include relevant motivations and context. List any dependencies that are required for this change.
+
+### Styleguides
+
+#### Git Commit Messages
+
+- Use the present tense ("Add feature" not "Added feature").
+- Use the imperative mood ("Move cursor to..." not "Moves cursor to...").
+- Limit the first line to 72 characters or less.
+- Reference issues and pull requests liberally after the first line.
+
+#### Code Style for rust
+
+- Follow the [Rust style guide](https://doc.rust-lang.org/1.0.0/style/README.html) for Rust code.
+- Ensure you run lint checks before submitting your pull request.
+
+### Community
+
+- If you have any questions about how to interpret the guidelines or want to discuss a substantial change/idea, don’t hesitate to post on our community channels or directly on GitHub issues.
+
+### Thank You!
+
+Every contribution counts, and by participating, you are expected to uphold this code. We appreciate your effort, and are excited to welcome you aboard and see what you can bring to the project!
+
+Let's create something amazing together!

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "openapi-mocker"
-version = "0.1.1"
+version = "0.1.2"
 edition = "2021"
 repository = "https://github.com/pachecoio/openapi-mocker"
 keywords = ["openapi", "mock", "mock-server"]

readme.md

@@ -32,8 +32,10 @@ cargo install openapi-mocker
                                     properties:
                                         message:
                                             type: string
-                                    example:
-                                        message: Hello, world!
+                                examples:
+                                    default:
+                                        value:
+                                            message: Hello, world!
                     '400':
                         description: Bad Request
                         content:
@@ -43,13 +45,12 @@ cargo install openapi-mocker
                                     properties:
                                         message:
                                             type: string
-                                    example:
-                                        message: Bad request
+                                examples:
+                                    default:
+                                        value:
+                                            message: Bad request
     ```
 
-    > Note: The `example` field under the `content.schema` object is used
-    to generate the mock response.
-
 2. Run the mock server:
 
     ```bash
@@ -91,30 +92,187 @@ cargo install openapi-mocker
 
 ## Performing requests
 
-The mock server will respond to any request with a response defined in the OpenAPI specification.
-If the request does not match any of the paths defined in the specification, the server will respond with a 404 Not Found.
+You can use custom examples defined in the OpenAPI specification to test different responses.
+Custom examples can be defined and requested in different ways.
 
-By default, requesting an existing path defined in the specification will return a 200 response
-with the example response defined in the specification.
+## Requesting by path
 
-### Request different status codes
+You can define an example with the exact path you want to match.
+Example:
+
+    ```yaml
+    openapi: 3.0.0
+    info:
+      title: Example API
+      version: 1.0.0
+    paths:
+        /hello/{name}:
+            get:
+                responses:
+                    '200':
+                        description: OK
+                        content:
+                            application/json:
+                                schema:
+                                    type: object
+                                    properties:
+                                        message:
+                                            type: string
+                                examples:
+                                    default:
+                                        value:
+                                            message: Hello, world!
+                                    /hello/jon_snow:
+                                        value:
+                                            message: You know nothing, Jon Snow!
+    ```
 
-To request a different status code, use the base url with the status code as a path parameter.
+Request the example by the exact path:
+    ```bash
+    curl -i http://localhost:8080/hello/jon_snow
+    ```
+
+    The response should be:
+
+    ```json
+    {"message":"You know nothing, Jon Snow!"}
+    ```
 
-For example, to request a 400 response example:
+Request the default example:
+    ```bash
+    curl -i http://localhost:8080/hello/arya_stark
+    ```
+
+    The response should be:
+
+    ```json
+    {"message":"Hello, world!"}
+    ```
 
-```bash
-curl -i http://localhost:8080/400/hello
-```
+## Requesting by query parameter
 
-The response should be:
+You can define an example with a query parameter you want to match.
 
-```json
-{"message":"Bad request"}
-```
+Example:
+
+    ```yaml
+    openapi: 3.0.0
+    info:
+      title: Example API
+      version: 1.0.0
+    paths:
+        /hello:
+            get:
+                parameters:
+                    - name: name
+                      in: query
+                      required: true
+                      schema:
+                        type: string
+                responses:
+                    '200':
+                        description: OK
+                        content:
+                            application/json:
+                                schema:
+                                    type: object
+                                    properties:
+                                        message:
+                                            type: string
+                                examples:
+                                    default:
+                                        value:
+                                            message: Hello, world!
+                                    "query:name=sansa":
+                                        value:
+                                            message: Sansa Stark
+    ```
+
+Request the example by the query parameter:
+    ```bash
+    curl -i http://localhost:8080/hello?name=sansa
+    ```
+    The response should be:
+    ```json
+    {"message": "Sansa Stark"}
+    ```
+
+Request that does not match the query parameter:
+    ```bash
+    curl -i http://localhost:8080/hello?name=arya
+    ```
+    The response should be:
+    ```json
+    {"message": "Hello, world!"}
+    ```
+
+## Requesting by headers
+
+You can define an example with a header you want to match.
+
+Example:
+
+    ```yaml
+    openapi: 3.0.0
+    info:
+      title: Example API
+      version: 1.0.0
+    paths:
+        /hello:
+            get:
+                parameters:
+                    - name: name
+                      in: header
+                      required: true
+                      schema:
+                        type: string
+                responses:
+                    '200':
+                        description: OK
+                        content:
+                            application/json:
+                                schema:
+                                    type: object
+                                    properties:
+                                        message:
+                                            type: string
+                                examples:
+                                    default:
+                                        value:
+                                            message: Hello, world!
+                                    "header:x-name=tyrion":
+                                        value:
+                                            message: Tyrion Lannister
+    ```
+
+Request the example by the header:
+    ```bash
+    curl -i http://localhost:8080/hello -H "x-name: tyrion"
+    ```
+    The response should be:
+    ```json
+    {"message": "Tyrion Lannister"}
+    ```
+
+Request that does not match the header:
+    ```bash
+    curl -i http://localhost:8080/hello
+    ```
+    The response should be:
+    ```json
+    {"message": "Hello, world!"}
+    ```
+
+> Note: The matches occur in the following order: path, query, headers.
+> It is also important to note that the request is going to return the 
+> first match found in the order above. If no match is found, the default
+> example is going to be returned.
+
+> Note: The matches are applied accross all the examples and responses in the OpenAPI specification.
+
+## Contributing
 
-> Note: The status code must be defined in the OpenAPI specification.
-> Requesting a status code that is not defined in the specification will return a 404 Not Found.
+Contributions are welcome! Please see the [contributing guidelines](CONTRIBUTING.md).
 
 ## License
 

src/lib.rs

@@ -23,22 +23,16 @@
 //! You can then make requests to the server to get example responses.
 //! For example, to get a list of pets:
 //! ```sh
-//! curl http://localhost:8080/200/pets
+//! curl http://localhost:8080/pets
 //! ```
 //! This will return a list of pets from the example response in the spec.
-//! You can also specify a different status code in the URL:
-//! ```sh
-//! curl http://localhost:8080/404/pets
-//! ```
-//! This will return a 404 status code with the example response for a 404 error.
-//!
 use clap::Parser;
 use std::path::PathBuf;
+pub mod openapi;
 pub mod server;
-pub mod spec;
 
 #[derive(Parser)]
-#[clap(version = "0.1.0", author = "Thiago Pacheco")]
+#[clap(version = "0.1.2", author = "Thiago Pacheco")]
 pub struct Args {
     #[clap(index = 1)]
     pub spec: PathBuf,

src/main.rs

@@ -1,6 +1,7 @@
 use actix_web::{web, App, HttpServer};
 use clap::Parser;
 use openapi_mocker::{
+    openapi::spec::Spec,
     server::{get_scope, AppState},
     Args,
 };
@@ -11,7 +12,7 @@ async fn main() -> std::io::Result<()> {
     println!("Starting server with spec: {}", args.spec.display());
 
     let port = args.port.unwrap_or(8080);
-    let spec = oas3::from_path(&args.spec).expect("failed to load spec");
+    let spec = Spec::from_path(args.spec.to_str().unwrap_or("")).expect("Failed to load spec");
     let data = web::Data::new(AppState { spec });
 
     let server = HttpServer::new(move || App::new().app_data(data.clone()).service(get_scope()))

src/openapi/mod.rs

@@ -0,0 +1 @@
+pub mod spec;