Knife4j

https://github.com/xiaoymin/knife4j
Admin
Knife4j is an enhanced solution for integrating Swagger API documentation into Java MVC frameworks,...
Tokens:579,354
Snippets:3,094
Trust Score:9.4
License:Apache-2.0
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### Start project with npm start

Source: https://github.com/xiaoymin/knife4j/blob/dev/knife4j-front/knife4j-ui/README.md

Starts the development server for the project.

```bash
npm start
```

--------------------------------

### Install and run Knife4j Vue project

Source: https://github.com/xiaoymin/knife4j/blob/dev/knife4j-doc/docs/action/dotnetcore-knife4j-how.md

Commands to install dependencies and start the Knife4j Vue development server.

```bash
yarn install
yarn serve
```

--------------------------------

### Start development server with yarn run serve

Source: https://github.com/xiaoymin/knife4j/blob/dev/knife4j-vue/README.md

Compiles and hot-reloads the application for development. Use this during development to get live updates.

```bash
yarn run serve
```

--------------------------------

### YAML example with schema and examples

Source: https://github.com/xiaoymin/knife4j/blob/dev/knife4j-doc/gitee/docs/oas/OpenAPI3-specification.html

YAML equivalent of the JSON example, showing schema reference and examples for cat, dog, and frog. The frog example uses a $ref to an external example.

```yaml
application/json:
  schema:
    $ref: "#/components/schemas/Pet"
  examples:
    cat:
      summary: An example of a cat
      value:
        name: Fluffy
        petType: Cat
        color: White
        gender: male
        breed: Persian
    dog:
      summary: An example of a dog with a cat's name
      value:
        name: Puma
        petType: Dog
        color: Black
        gender: Female
        breed: Mixed
    frog:
      $ref: "#/components/examples/frog-example"
```

--------------------------------

### Paths Object Example (JSON)

Source: https://github.com/xiaoymin/knife4j/blob/dev/knife4j-doc/gitee/docs/oas/OpenAPI3-specification.html

Example of an OpenAPI 3 Paths Object in JSON format, showing a GET operation for /pets.

```json
{  "/pets": {    "get": {      "description": "Returns all pets from the system that the user has access to",      "responses": {        "200": {                    "description": "A list of pets.",          "content": {            "application/json": {              "schema": {                "type": "array",                "items": {                  "$ref": "#/components/schemas/pet"                }              }            }          }        }      }    }  }}
```

--------------------------------

### Paths Object Example (YAML)

Source: https://github.com/xiaoymin/knife4j/blob/dev/knife4j-doc/gitee/docs/oas/OpenAPI3-specification.html

Example of an OpenAPI 3 Paths Object in YAML format, showing a GET operation for /pets.

```yaml
/pets:  get:    description: Returns all pets from the system that the user has access to    responses:      '200':        description: A list of pets.        content:          application/json:            schema:              type: array              items:                $ref: '#/components/schemas/pet'
```

--------------------------------

### Install dependencies with yarn install

Source: https://github.com/xiaoymin/knife4j/blob/dev/knife4j-vue/README.md

Run this command to install all project dependencies as specified in package.json. This is the first step after cloning the repository.

```bash
yarn install
```

--------------------------------

### Java 实体类：无 example 值的字段

Source: https://github.com/xiaoymin/knife4j/blob/dev/knife4j-doc/docs/features/requestCache.md

当字段未定义 example 时，UI 界面不会显示默认值，开发者调试时填写的值会被缓存，并在第二次请求时作为默认值使用。

```java
public class SwaggerRequestBody{
    
    @ApiModelProperty(value="姓名")
    private String name;
    
    //more...
}
```

--------------------------------

### Java 实体类无 example 值

Source: https://github.com/xiaoymin/knife4j/blob/dev/knife4j-doc/gitee/docs/features/requestCache.html

当后端未设置 example 值时，Knife4j 在第二次请求时会启用上一次调试时填写的缓存值。

```java
public class SwaggerRequestBody{
        @ApiModelProperty(value="姓名")
    private String name;
        //more...
}
```

--------------------------------

### JSON example with schema and examples

Source: https://github.com/xiaoymin/knife4j/blob/dev/knife4j-doc/gitee/docs/oas/OpenAPI3-specification.html

Shows a JSON request body with a schema reference and two inline examples (cat and dog) plus a $ref to an external example. The schema references #/components/schemas/Pet.

```json
{  "application/json": {    "schema": {         "$ref": "#/components/schemas/Pet"    },    "examples": {      "cat" : {
        "summary": "An example of a cat",
        "value": 
          {
            "name": "Fluffy",
            "petType": "Cat",
            "color": "White",
            "gender": "male",
            "breed": "Persian"
          }
      },
      "dog": {
        "summary": "An example of a dog with a cat's name",
        "value" :  {
           "name": "Puma",
          "petType": "Dog",
          "color": "Black",
          "gender": "Female",
          "breed": "Mixed"
        },
      "frog": {
          "$ref": "#/components/examples/frog-example"
        }
      }
    }
  }}
}
```

--------------------------------

### Info Object example (JSON)

Source: https://github.com/xiaoymin/knife4j/blob/dev/knife4j-doc/gitee/docs/oas/OpenAPI3-specification.html

JSON example of the Info Object with title, description, termsOfService, contact, license, and version fields.

```json
{  "title": "Sample Pet Store App",  "description": "This is a sample server for a pet store.",  "termsOfService": "http://example.com/terms/",  "contact": {    "name": "API Support",    "url": "http://www.example.com/support",    "email": "support@example.com"  },  "license": {    "name": "Apache 2.0",    "url": "https://www.apache.org/licenses/LICENSE-2.0.html"  },  "version": "1.0.1"}
```

--------------------------------

### Java 实体类：带 example 值的字段

Source: https://github.com/xiaoymin/knife4j/blob/dev/knife4j-doc/docs/features/requestCache.md

当字段使用 @ApiModelProperty 的 example 属性时，Knife4j 每次打开接口请求参数都会使用该 example 值，不会使用调试时缓存的值。

```java
public class SwaggerRequestBody{
    
    @ApiModelProperty(value="姓名",example="张飞")
    private String name;
    
    //more...
}
```

--------------------------------

### Path Item Object example in YAML

Source: https://github.com/xiaoymin/knife4j/blob/dev/knife4j-doc/gitee/docs/oas/OpenAPI3-specification.html

YAML representation of a Path Item Object with a get operation and parameters. The get operation has a description, summary, operationId, and responses. The parameters include a required path parameter 'id' with an array schema and simple style.

```yaml
get:
  description: Returns pets based on ID
  summary: Find pets by ID
  operationId: getPetsById
  responses:
    '200':
      description: pet response
      content:
        '*/*':
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Pet'
    default:
      description: error payload
      content:
        'text/html':
          schema:
            $ref: '#/components/schemas/ErrorModel'
parameters:
- name: id
  in: path
  description: ID of pet to use
  required: true
  schema:
    type: array
    items:
      type: string
  style: simple
```

--------------------------------

### Info Object example (YAML)

Source: https://github.com/xiaoymin/knife4j/blob/dev/knife4j-doc/gitee/docs/oas/OpenAPI3-specification.html

YAML example of the Info Object with the same fields as the JSON example.

```yaml
title: Sample Pet Store Appdescription: This is a sample server for a pet store.termsOfService: http://example.com/terms/contact:  name: API Support  url: http://www.example.com/support  email: support@example.comlicense:  name: Apache 2.0  url: https://www.apache.org/licenses/LICENSE-2.0.htmlversion: 1.0.1
```

--------------------------------

### Key Example

Source: https://github.com/xiaoymin/knife4j/blob/dev/knife4j-doc/gitee/docs/oas/OpenAPI3-specification.html

Example of a key in OpenAPI 3, showing a simple key-value pair.

```text
UserUser_1User_Nameuser-namemy.org.User
```

--------------------------------

### Java 实体类定义 example 值

Source: https://github.com/xiaoymin/knife4j/blob/dev/knife4j-doc/gitee/docs/features/requestCache.html

当后端在 Swagger 注解中为字段设置 example 值时，Knife4j 每次打开接口都会使用该默认值，不会缓存调试时填写的值。

```java
public class SwaggerRequestBody{
        @ApiModelProperty(value="姓名",example="张飞")
    private String name;
        //more...
}
```

--------------------------------

### Path Matching Example - Valid

Source: https://github.com/xiaoymin/knife4j/blob/dev/knife4j-doc/gitee/docs/oas/OpenAPI3-specification.html

Example of a valid path matching pattern for /pets/mine.

```text
/pets/{petId}/pets/mine
```

--------------------------------

### Path Matching Example - Ambiguous

Source: https://github.com/xiaoymin/knife4j/blob/dev/knife4j-doc/gitee/docs/oas/OpenAPI3-specification.html

Example of an ambiguous path matching pattern.

```text
/{entity}/me/books/{id}
```

--------------------------------

### Link Object example with operationId and parameters

Source: https://github.com/xiaoymin/knife4j/blob/dev/knife4j-doc/gitee/docs/oas/OpenAPI3-specification.html

Shows a Link Object definition using operationId to reference the target operation and parameters using runtime expressions like $request.path.id. The example includes the path item for the linked operation.

```yaml
paths:
  /users/{id}:
    parameters:
    - name: id
      in: path
      required: true
      description: the user identifier, as userId
      schema:
        type: string
    get:
      responses:
        '200':
          description: the user being returned
          content:
            application/json:
              schema:
                type: object
                properties:
                  uuid: # the unique user id
                    type: string
                    format: uuid
          links:
            address:
              # the target link operationId
              operationId: getUserAddress
              parameters:
                # get the `id` field from the request path parameter named `id`
                userId: $request.path.id
  # the path item of the linked operation
  /users/{userid}/address:
    parameters:
    - name: userid
      in: path
      required: true
      description: the user identifier, as userId
      schema:
        type: string
    # linked operation
    get:
      operationId: getUserAddress
      responses:
        '200':
          description: the user's address
```

--------------------------------

### Object Example (YAML)

Source: https://github.com/xiaoymin/knife4j/blob/dev/knife4j-doc/gitee/docs/oas/OpenAPI3-specification.html

Example of an OpenAPI 3 object definition in YAML format, including schemas, parameters, responses, and security schemes.

```yaml
components:  schemas:    GeneralError:      type: object      properties:        code:          type: integer          format: int32        message:          type: string    Category:      type: object      properties:        id:          type: integer          format: int64        name:          type: string    Tag:      type: object      properties:        id:          type: integer          format: int64        name:          type: string  parameters:    skipParam:      name: skip      in: query      description: number of items to skip      required: true      schema:        type: integer        format: int32    limitParam:      name: limit      in: query      description: max records to return      required: true      schema:        type: integer        format: int32  responses:    NotFound:      description: Entity not found.    IllegalInput:      description: Illegal input for operation.    GeneralError:      description: General Error      content:        application/json:          schema:            $ref: '#/components/schemas/GeneralError'  securitySchemes:    api_key:      type: apiKey      name: api_key      in: header    petstore_auth:      type: oauth2      flows:         implicit:          authorizationUrl: http://example.org/api/oauth/dialog          scopes:            write:pets: modify pets in your account            read:pets: read your pets
```

--------------------------------

### Path Matching Example - Invalid

Source: https://github.com/xiaoymin/knife4j/blob/dev/knife4j-doc/gitee/docs/oas/OpenAPI3-specification.html

Example of an invalid path matching pattern that is identical and invalid.

```text
/pets/{petId}/pets/{name}
```

--------------------------------

### Responses Object example in YAML

Source: https://github.com/xiaoymin/knife4j/blob/dev/knife4j-doc/gitee/docs/oas/OpenAPI3-specification.html

Shows the same response object in YAML format, with a 200 status and default error response.

```yaml
'200':  description: a pet to be returned  content:     application/json:      schema:        $ref: '#/components/schemas/Pet'default:  description: Unexpected error  content:    application/json:      schema:        $ref: '#/components/schemas/ErrorModel
```

--------------------------------

### Object Example (JSON)

Source: https://github.com/xiaoymin/knife4j/blob/dev/knife4j-doc/gitee/docs/oas/OpenAPI3-specification.html

Example of an OpenAPI 3 object definition in JSON format, including schemas, parameters, responses, and security schemes.

```json
"components": {  "schemas": {    "GeneralError": {      "type": "object",      "properties": {        "code": {          "type": "integer",          "format": "int32"        },        "message": {          "type": "string"        }      }    },    "Category": {      "type": "object",      "properties": {        "id": {          "type": "integer",          "format": "int64"        },        "name": {          "type": "string"        }      }    },    "Tag": {      "type": "object",      "properties": {        "id": {          "type": "integer",          "format": "int64"        },        "name": {          "type": "string"        }      }    }  },  "parameters": {    "skipParam": {      "name": "skip",      "in": "query",      "description": "number of items to skip",      "required": true,      "schema": {        "type": "integer",        "format": "int32"      }    },    "limitParam": {      "name": "limit",      "in": "query",      "description": "max records to return",      "required": true,      "schema" : {        "type": "integer",        "format": "int32"      }    }  },  "responses": {    "NotFound": {      "description": "Entity not found."    },    "IllegalInput": {      "description": "Illegal input for operation."    },    "GeneralError": {      "description": "General Error",      "content": {        "application/json": {          "schema": {            "$ref": "#/components/schemas/GeneralError"          }        }      }    }  },  "securitySchemes": {    "api_key": {      "type": "apiKey",      "name": "api_key",      "in": "header"    },    "petstore_auth": {      "type": "oauth2",      "flows": {        "implicit": {          "authorizationUrl": "http://example.org/api/oauth/dialog",          "scopes": {            "write:pets": "modify pets in your account",            "read:pets": "read your pets"          }        }      }    }  }}
```

--------------------------------

### Callback Object example with fixed server and request body parameters

Source: https://github.com/xiaoymin/knife4j/blob/dev/knife4j-doc/gitee/docs/oas/OpenAPI3-specification.html

Defines a callback URL with a fixed server, but the query string parameters are filled from the 'id' and 'email' properties in the request body.

```yaml
transactionCallback:  'http://notificationServer.com?transactionId={$request.body#/id}&email={$request.body#/email}':    post:      requestBody:        description: Callback payload        content:           'application/json':            schema:              $ref: '#/components/schemas/SomePayload'      responses:        '200':          description: callback successfully processed
```

--------------------------------

### YAML example of discriminated models (Pet, Cat, Dog)

Source: https://github.com/xiaoymin/knife4j/blob/dev/knife4j-doc/gitee/docs/oas/OpenAPI3-specification.html

YAML equivalent of the JSON example, defining the same Pet, Cat, and Dog schemas with a discriminator. The YAML uses comments to indicate the discriminator values for Cat and Dog. This is the alternative representation of the same model.

```yaml
components:  schemas:    Pet:      type: object      discriminator:        propertyName: petType      properties:        name:          type: string        petType:          type: string      required:      - name      - petType    Cat:  ## "Cat" will be used as the discriminator value      description: A representation of a cat      allOf:      - $ref: '#/components/schemas/Pet'      - type: object        properties:          huntingSkill:            type: string            description: The measured skill for hunting            enum:            - clueless            - lazy            - adventurous            - aggressive        required:        - huntingSkill    Dog:  ## "Dog" will be used as the discriminator value      description: A representation of a dog      allOf:      - $ref: '#/components/schemas/Pet'      - type: object        properties:          packSize:            type: integer            format: int32            description: the size of the pack the dog is from            default: 0            minimum: 0        required:        - packSize
```
Tokens:
Raw