Rust OpenAPI 3.0 docs generator
Or see more here
```rust use opg::*; use serde::{Serialize, Deserialize};
enum SimpleEnum { Test, Another, Yay, }
struct NewType(String);
struct SimpleStruct { first_field: i32, #[opg("Field description")] second: String, }
enum ExternallyTaggedEnum { Test(String), AnotherTest(String, #[opg("Second")] String), }
enum UntaggedEnum { First { value: NewType, }, #[opg("Variant description")] Second { #[opg("Inlined struct", inline)] another: SimpleStruct, }, }
enum InternallyTaggedEnum { First(SimpleStruct), Second { field: String }, }
enum AdjacentlyTaggedEnum { First(String), Second(NewType, NewType), }
struct TypeChangedStruct { #[serde(with = "chrono::naive::serde::ts_milliseconds")] #[opg("UTC timestamp in milliseconds", integer, format = "int64")] pub timestamp: chrono::NaiveDateTime, }
struct StructWithComplexObjects {
#[serde(skipserializingif = "Option::isnone")]
#[opg(optional)]
superoptional: Option
struct GenericStructWithRef<'a, T> { message: &'a str, test: T, }
struct SuperResponse { simpleenum: SimpleEnum, #[serde(rename = "newtype")] newtype: NewType, externallytaggedenum: ExternallyTaggedEnum, untaggedenum: UntaggedEnum, internallytaggedenum: InternallyTaggedEnum, adjacentlytaggedenum: AdjacentlyTaggedEnum, typechangedstruct: TypeChangedStruct, structwithcomplexobjects: StructWithComplexObjects, }
fn printapi() { let test = describeapi! { info: { title: "My super API", version: "0.0.0", }, tags: {internal, admin("Super admin methods")}, servers: { "https://my.super.server.com/v1", }, securityschemes: { (http "bearerAuth"): { scheme: Bearer, bearerformat: "JWT", }, }, paths: { ("hello" / "world" / { paramTest: String }): { summary: "Some test group of requests", description: "Another test description", parameters: { (header "x-request-id"): { description: "Test", required: true, }, }, GET: { tags: {internal}, summary: "Small summary", description: "Small description", parameters: { (query someParam: u32): { description: "Test", } }, 200: String, }, POST: { tags: {admin}, security: {"basicAuth"}, body: { description: "Some interesting description", schema: GenericStructWithRef<'static, i64>, required: true, }, 200: SuperResponse, } } } };
println!("{}", serde_yaml::to_string(&test).unwrap());
} ```
Result:
```yaml --- openapi: 3.0.3 info: title: My super API version: 0.0.0 tags: - name: admin description: Super admin methods - name: internal servers: - url: "https://my.super.server.com/v1" paths: "/hello/world/{paramTest}": summary: Some test group of requests description: Another test description get: tags: - internal summary: Small summary description: Small description responses: 200: description: OK content: application/json: schema: type: string parameters: - name: someParam description: Test in: query schema: type: integer format: uint32 post: tags: - admin security: - basicAuth: [] requestBody: required: true description: Some interesting description content: application/json: schema: $ref: "#/components/schemas/GenericStructWithRef" responses: 200: description: OK content: application/json: schema: $ref: "#/components/schemas/SuperResponse" parameters: - name: paramTest in: path required: true schema: type: string - name: x-request-id description: Test in: header required: true schema: type: string components: schemas: AdjacentlyTaggedEnum: type: object properties: content: oneOf: - type: string - type: array items: oneOf: - $ref: "#/components/schemas/NewType" - $ref: "#/components/schemas/NewType" tag: description: AdjacentlyTaggedEnum type variant type: string enum: - first - second example: first required: - tag - content ExternallyTaggedEnum: type: object additionalProperties: oneOf: - type: string - type: array items: oneOf: - type: string - description: Second type: string GenericStructWithRef: type: object properties: message: type: string test: type: integer format: int64 required: - message - test InternallyTaggedEnum: oneOf: - type: object properties: first_field: type: integer format: int32 second: description: Field description type: string tag: description: InternallyTaggedEnum type variant type: string enum: - first example: first required: - first_field - second - tag - type: object properties: field: type: string tag: description: InternallyTaggedEnum type variant type: string enum: - second example: second required: - field - tag NewType: description: newtype string type: string format: id example: abcd0001 SimpleEnum: description: Simple enum type: string enum: - test - another - yay example: test StructWithComplexObjects: type: object properties: boxed: nullable: true type: integer format: int32 field: nullable: true type: string super_optional: nullable: true type: string required: - field - boxed SuperResponse: type: object properties: adjacently_tagged_enum: $ref: "#/components/schemas/AdjacentlyTaggedEnum" externally_tagged_enum: $ref: "#/components/schemas/ExternallyTaggedEnum" internally_tagged_enum: $ref: "#/components/schemas/InternallyTaggedEnum" new_type: $ref: "#/components/schemas/NewType" simple_enum: $ref: "#/components/schemas/SimpleEnum" struct_with_complex_objects: $ref: "#/components/schemas/StructWithComplexObjects" type_changed_struct: $ref: "#/components/schemas/TypeChangedStruct" untagged_enum: $ref: "#/components/schemas/UntaggedEnum" required: - simple_enum - new_type - externally_tagged_enum - untagged_enum - internally_tagged_enum - adjacently_tagged_enum - type_changed_struct - struct_with_complex_objects TypeChangedStruct: type: object properties: timestamp: description: UTC timestamp in milliseconds type: integer format: int64 required: - timestamp UntaggedEnum: oneOf: - type: object properties: value: $ref: "#/components/schemas/NewType" required: - value - description: Variant description type: object properties: another: description: Inlined struct type: object properties: first_field: type: integer format: int32 second: description: Field description type: string required: - first_field - second required: - another securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ```