fix: adjust documentation (#31)

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Author: dotkas

README.md

@@ -0,0 +1,9 @@
+# Documentation
+
+Deep-dive docs for `oapi-codegen-rust`. See the [root README](../README.md) for
+a quickstart.
+
+- [Installation](installation.md)
+- [Configuration](configuration.md) — CLI and config-file reference
+- [OpenAPI extensions](extensions.md) — supported vendor extension keys
+- [Design decisions vs. Go](design.md) — where and why we deviate from `oapi-codegen`

docs/README.md

@@ -0,0 +1,62 @@
+# Configuration
+
+## CLI
+
+```sh
+oapi-codegen [--config <cfg.yaml>] [--output <out.rs>] <spec.yaml>
+```
+
+- `<spec>` — path to the OpenAPI 3 document (YAML or JSON). Required.
+- `--config, -c` — path to a YAML config file. Without one, only models are
+  generated.
+- `--output, -o` — output file (overrides `output` in the config). Prints to
+  stdout if unset.
+
+## Config file
+
+Keys mirror [`oapi-codegen`](https://github.com/oapi-codegen/oapi-codegen)'s
+YAML config; unknown keys are ignored, so an existing Go config can be reused
+as-is. Only the subset below is interpreted.
+
+| Key              | Type   | Purpose                                                                |
+| ---------------- | ------ | ---------------------------------------------------------------------- |
+| `package`        | string | Target module name (informational).                                    |
+| `output`         | path   | Output file path.                                                      |
+| `import-mapping` | map    | Map referenced spec files to external Rust modules (multi-file specs). |
+
+### `generate`
+
+| Key               | Purpose                                                |
+| ----------------- | ------------------------------------------------------ |
+| `models`          | Emit structs/enums from component schemas.             |
+| `std-http-server` | Emit an axum server interface (`trait Api` + router).  |
+| `client`          | Emit a blocking `reqwest` client.                      |
+| `server-urls`     | Emit constants/builders for the spec's `servers` URLs. |
+| `embedded-spec`   | _Not implemented_ — rejected if set.                   |
+
+Setting both `std-http-server` and `client` emits them into `server` / `client`
+submodules with shared models at the root.
+
+### `output-options`
+
+| Key                     | Purpose                                                       |
+| ----------------------- | ------------------------------------------------------------- |
+| `skip-prune`            | Keep schemas not referenced by any retained operation/schema. |
+| `include-tags`          | Only generate operations with one of these tags.              |
+| `exclude-tags`          | Skip operations with any of these tags.                       |
+| `include-operation-ids` | Only generate these `operationId`s.                           |
+| `exclude-operation-ids` | Skip these `operationId`s.                                    |
+| `exclude-schemas`       | Drop these component schemas before lowering.                 |
+
+## Example
+
+```yaml
+package: restapi
+output: generated/restapi.rs
+generate:
+  std-http-server: true
+  models: true
+  server-urls: true
+import-mapping:
+  schemas/common.yaml: crate::apimodel::common
+```

docs/configuration.md

@@ -0,0 +1,66 @@
+# Design decisions vs. Go
+
+Rust differs enough from Go that a faithful port makes different choices in
+places. This lists where `oapi-codegen-rust` deviates from
+[`oapi-codegen`](https://github.com/oapi-codegen/oapi-codegen) and why.
+
+## Server: native async trait, axum only
+
+- **Go:** generates for many frameworks (chi, echo, gin, fiber, gorilla, iris,
+  stdhttp) from a plain-method interface.
+- **Rust:** one `trait Api` using native async-fn-in-traits
+  (`fn op(&self, ..) -> impl Future<Output = ..> + Send`), targeting axum 0.8.
+  No `async-trait` dependency.
+- **Why:** stable Rust does async-in-traits natively; one well-supported
+  framework keeps output idiomatic without a macro dependency.
+- There is a single server mode — a typed `trait Api`, comparable to Go's
+  strict server. There is no unstructured handler variant.
+
+## Typed status-code response enums
+
+- **Go:** per-status response structs / context returns.
+- **Rust:** one `enum <Op>Response` per operation with a variant per declared
+  status. The same enum implements `IntoResponse` on the server and is the
+  client's success type, so a new status is a compile-enforced exhaustive match
+  on both sides.
+
+## Token-based generation, not templates
+
+- **Go:** user-overridable `text/template`.
+- **Rust:** build a `TokenStream` with `quote!`, parse to `syn::File` (which
+  guarantees syntactically valid Rust), and pretty-print with `prettyplease`.
+
+## Blocking `reqwest` client
+
+- Returns `Result<<Op>Response, ClientError>` with a single hand-written
+  `ClientError` enum. Blocking by default, so no async runtime is forced on
+  consumers.
+
+## Derive HTTP status semantics
+
+- Status codes come from the `http` / `axum` / `reqwest` `StatusCode` types
+  rather than a hand-maintained reason/table mirror.
+
+## Vendor extensions
+
+- `x-rust-type`, `x-rust-name`, `x-rust-serde-skip`, plus `oapi-codegen`
+  compatibility keys (`x-omitempty`, `x-order`, `x-deprecated-reason`,
+  `x-enum-varnames` / `x-enumNames`).
+- `x-go-*` keys are ignored (accepted, no effect). See
+  [extensions](extensions.md).
+
+## Combined output via submodules
+
+- Emitting server and client together puts shared component models at the crate
+  root and the two targets in `server` / `client` submodules, resolving the
+  same-named/different-shaped per-operation items.
+
+## OpenAPI 3.0
+
+- The generator reads OpenAPI 3.0 documents (via the `openapiv3` crate).
+
+## Config compatibility
+
+- The YAML config mirrors `oapi-codegen`'s keys, and unknown keys are ignored,
+  so an existing Go config can be reused as-is. See
+  [configuration](configuration.md).

docs/design.md

@@ -0,0 +1,35 @@
+# OpenAPI extensions
+
+The generator honors the vendor extensions below. Rust-specific behaviour uses
+`x-rust-*` keys; the rest are `oapi-codegen` compatibility keys. Any other
+extension — including the Go type keys `x-go-type`, `x-go-name`,
+`x-go-json-ignore` — is ignored (accepted, but has no effect); use the
+`x-rust-*` equivalents instead.
+
+| Extension                         | Applies to        | Effect                                                          |
+| --------------------------------- | ----------------- | --------------------------------------------------------------- |
+| `x-rust-type`                     | schema            | Emit this verbatim Rust type instead of a generated one.        |
+| `x-rust-name`                     | schema / property | Override the generated type or field identifier.                |
+| `x-rust-serde-skip`               | property          | Drop the field with `#[serde(skip)]`.                           |
+| `x-omitempty`                     | property          | Force `skip_serializing_if` on/off, overriding the default.     |
+| `x-order`                         | property          | Order struct fields explicitly (1-indexed).                     |
+| `x-deprecated-reason`             | schema / property | Note for `#[deprecated]`; honored only when `deprecated: true`. |
+| `x-enum-varnames` / `x-enumNames` | enum schema       | Override generated enum variant identifiers, positionally.      |
+
+## Example
+
+```yaml
+components:
+  schemas:
+    Widget:
+      type: object
+      properties:
+        id:
+          type: string
+          x-rust-name: widget_id
+        cached_at:
+          type: string
+          x-rust-serde-skip: true
+        raw:
+          x-rust-type: serde_json::Value
+```

docs/extensions.md

@@ -0,0 +1,27 @@
+# Installation
+
+## Install
+
+```sh
+cargo install oapi-codegen
+```
+
+Verify:
+
+```sh
+oapi-codegen --version
+```
+
+## From source
+
+```sh
+git clone https://github.com/alchemaxinc/oapi-codegen-rust
+cd oapi-codegen-rust
+cargo install --path crates/oapi-codegen
+```
+
+Or run it in-tree without installing:
+
+```sh
+cargo run -p oapi-codegen -- --help
+```