\u5728\u524d\u540e\u7aef\u5206\u79bb\u7684\u5f00\u53d1\u6a21\u5f0f\u4e0b，\u63a5\u53e3\u6587\u6863\u7684\u7ef4\u62a4\u4e00\u76f4\u662f\u4e2a\u75db\u70b9\u3002Swagger \u4f5c\u4e3a\u4e00\u5957\u5f00\u6e90\u7684 API \u6587\u6863\u5de5\u5177\u94fe，\u80fd\u591f\u6839\u636e\u4ee3\u7801\u81ea\u52a8\u751f\u6210\u63a5\u53e3\u6587\u6863，\u5e76\u63d0\u4f9b\u53ef\u89c6\u5316\u7684\u8c03\u8bd5\u754c\u9762，\u6781\u5927\u63d0\u5347\u4e86\u5f00\u53d1\u534f\u4f5c\u6548\u7387\u3002\u672c\u6587\u5c06\u4ece Swagger \u7684\u6838\u5fc3\u7ec4\u4ef6\u5165\u624b，\u7ed3\u5408\u4e30\u5bcc\u7684\u4ee3\u7801\u5b9e\u4f8b，\u5e2e\u52a9\u8bfb\u8005\u6df1\u5165\u7406\u89e3\u5176\u5de5\u4f5c\u539f\u7406\u4e0e\u4f7f\u7528\u65b9\u6cd5\u3002<\/p>\n
Swagger \u5e76\u975e\u5355\u4e00\u5de5\u5177，\u800c\u662f\u4e00\u5957\u56f4\u7ed5 OpenAPI \u89c4\u8303（\u539f Swagger \u89c4\u8303）\u6784\u5efa\u7684\u5de5\u5177\u96c6\u5408\u3002\u7406\u89e3\u8fd9\u4e9b\u7ec4\u4ef6\u4e4b\u95f4\u7684\u5173\u7cfb，\u662f\u638c\u63e1 Swagger \u7684\u7b2c\u4e00\u6b65\u3002<\/p>\n
OpenAPI \u89c4\u8303\u662f\u6574\u4e2a Swagger \u751f\u6001\u7684\u6838\u5fc3\u3002\u5b83\u4f7f\u7528 JSON \u6216 YAML \u683c\u5f0f\u63cf\u8ff0\u63a5\u53e3\u7684\u8def\u5f84\u3001\u53c2\u6570\u3001\u8bf7\u6c42\u4f53\u3001\u54cd\u5e94\u7b49\u4fe1\u606f\u3002\u4e0b\u9762\u662f\u4e00\u4e2a\u6807\u51c6\u7684 OpenAPI \u6587\u6863\u793a\u4f8b：<\/p>\n
openapi: 3.0.0
\ninfo:
\n title: \u7528\u6237\u7ba1\u7406 API
\n version: 1.0.0
\n description: \u63d0\u4f9b\u7528\u6237\u4fe1\u606f\u7684\u589e\u5220\u6539\u67e5\u63a5\u53e3
\npaths:
\n \/users\/{id}:
\n get:
\n summary: \u6839\u636e ID \u67e5\u8be2\u7528\u6237
\n parameters:
\n – name: id
\n in: path
\n required: true
\n schema:
\n type: integer
\n responses:
\n '200':
\n description: \u67e5\u8be2\u6210\u529f
\n content:
\n application\/json:
\n schema:
\n $ref: '#\/components\/schemas\/User'
\ncomponents:
\n schemas:
\n User:
\n type: object
\n properties:
\n id:
\n type: integer
\n name:
\n type: string
\n email:
\n type: string<\/p>\n
\u8be5\u89c4\u8303\u5b9a\u4e49\u4e86 API \u7684\u5143\u4fe1\u606f\u3001\u8def\u5f84\u3001\u53c2\u6570\u548c\u54cd\u5e94\u7ed3\u6784\u3002Swagger UI \u6b63\u662f\u57fa\u4e8e\u8fd9\u4efd\u6587\u6863\u6e32\u67d3\u51fa\u53ef\u4ea4\u4e92\u7684\u8c03\u8bd5\u9875\u9762\u3002<\/p>\n
Swagger UI \u662f\u4e00\u4e2a\u7eaf\u524d\u7aef\u7684\u9759\u6001\u8d44\u6e90\u7ec4\u4ef6，\u5b83\u8bfb\u53d6 OpenAPI \u6587\u6863\u5e76\u6e32\u67d3\u4e3a\u7f8e\u89c2\u7684\u63a5\u53e3\u6587\u6863\u9875\u9762\u3002\u5728 Spring Boot \u9879\u76ee\u4e2d，\u901a\u5e38\u901a\u8fc7\u4f9d\u8d56\u5f15\u5165\u5e76\u81ea\u52a8\u88c5\u914d\u3002<\/p>\n
\u4e0b\u9762\u6f14\u793a\u5982\u4f55\u5728 Spring Boot \u9879\u76ee\u4e2d\u96c6\u6210 Swagger UI\u3002\u9996\u5148\u6dfb\u52a0 Maven \u4f9d\u8d56：<\/p>\n
<dependency>
\n <groupId>io.springfox<\/groupId>
\n <artifactId>springfox-boot-starter<\/artifactId>
\n <version>3.0.0<\/version>
\n<\/dependency><\/p>\n
\u7136\u540e\u521b\u5efa\u914d\u7f6e\u7c7b，\u542f\u7528 Swagger \u5e76\u914d\u7f6e\u6587\u6863\u57fa\u672c\u4fe1\u606f：<\/p>\n
import org.springframework.context.annotation.Bean;
\nimport org.springframework.context.annotation.Configuration;
\nimport springfox.documentation.builders.ApiInfoBuilder;
\nimport springfox.documentation.builders.PathSelectors;
\nimport springfox.documentation.builders.RequestHandlerSelectors;
\nimport springfox.documentation.service.ApiInfo;
\nimport springfox.documentation.spi.DocumentationType;
\nimport springfox.documentation.spring.web.plugins.Docket;
\n@Configuration
\npublic class SwaggerConfig {
\n@Bean
\npublic Docket createRestApi() {
\n return new Docket(DocumentationType.OAS_30)
\n .apiInfo(apiInfo())
\n .select()
\n .apis(RequestHandlerSelectors.basePackage("com.example.controller"))
\n .paths(PathSelectors.any())
\n .build();
\n}
\nprivate ApiInfo apiInfo() {
\nreturn new ApiInfoBuilder()
\n.title("\u7528\u6237\u7ba1\u7406 API \u6587\u6863")
\n.description("\u57fa\u4e8e Swagger 3 \u81ea\u52a8\u751f\u6210\u7684\u63a5\u53e3\u6587\u6863")
\n.version("1.0.0")
\n.build();
\n}
\n}<\/p>\n
\u542f\u52a8\u9879\u76ee\u540e，\u8bbf\u95ee http:\/\/localhost:8080\/swagger-ui\/ \u5373\u53ef\u770b\u5230\u53ef\u89c6\u5316\u7684\u63a5\u53e3\u6587\u6863\u9875\u9762\u3002<\/p>\n
Swagger \u7684\u6838\u5fc3\u4ef7\u503c\u5728\u4e8e\u901a\u8fc7\u6ce8\u89e3\u81ea\u52a8\u751f\u6210\u6587\u6863，\u65e0\u9700\u624b\u5199\u7ef4\u62a4\u3002\u5e38\u7528\u7684\u6ce8\u89e3\u5305\u62ec @Api\u3001@ApiOperation\u3001@ApiParam \u548c @ApiModelProperty\u3002<\/p>\n
\u4e0b\u9762\u662f\u4e00\u4e2a\u4f7f\u7528\u6ce8\u89e3\u63cf\u8ff0\u63a5\u53e3\u7684 Controller \u793a\u4f8b：<\/p>\n
import io.swagger.annotations.Api;
\nimport io.swagger.annotations.ApiOperation;
\nimport io.swagger.annotations.ApiParam;
\nimport org.springframework.web.bind.annotation.*;
\n@Api(tags = "\u7528\u6237\u7ba1\u7406\u63a5\u53e3")
\n@RestController
\n@RequestMapping("\/users")
\npublic class UserController {
\n@ApiOperation(value = "\u6839\u636e ID \u67e5\u8be2\u7528\u6237", notes = "\u8fd4\u56de\u7528\u6237\u8be6\u7ec6\u4fe1\u606f")
\n@GetMapping("\/{id}")
\npublic User getUserById(
\n @ApiParam(name = "id", value = "\u7528\u6237 ID", required = true, example = "1")
\n @PathVariable Long id) {
\n return new User(id, "\u5f20\u4e09", "zhangsan@example.com");
\n}
\n@ApiOperation(value = "\u521b\u5efa\u7528\u6237", notes = "\u521b\u5efa\u6210\u529f\u540e\u8fd4\u56de\u7528\u6237 ID")
\n@PostMapping
\npublic Long createUser(@RequestBody User user) {
\nreturn user.getId();
\n}
\n}<\/p>\n
\u5bf9\u5e94\u7684\u5b9e\u4f53\u7c7b\u540c\u6837\u9700\u8981\u6dfb\u52a0\u6ce8\u89e3，\u4ee5\u4fbf\u6587\u6863\u5c55\u793a\u5b57\u6bb5\u542b\u4e49：<\/p>\n
import io.swagger.annotations.ApiModel;
\nimport io.swagger.annotations.ApiModelProperty;
\n@ApiModel(description = "\u7528\u6237\u5b9e\u4f53")
\npublic class User {
\n@ApiModelProperty(value = "\u7528\u6237 ID", example = "1")
\nprivate Long id;
\n@ApiModelProperty(value = "\u7528\u6237\u59d3\u540d", example = "\u5f20\u4e09")
\nprivate String name;
\n@ApiModelProperty(value = "\u90ae\u7bb1\u5730\u5740", example = "zhangsan@example.com")
\nprivate String email;
\npublic User() {
\n}
\npublic User(Long id, String name, String email) {
\nthis.id = id;
\nthis.name = name;
\nthis.email = email;
\n}
\npublic Long getId() {
\nreturn id;
\n}
\npublic void setId(Long id) {
\nthis.id = id;
\n}
\npublic String getName() {
\nreturn name;
\n}
\npublic void setName(String name) {
\nthis.name = name;
\n}
\npublic String getEmail() {
\nreturn email;
\n}
\npublic void setEmail(String email) {
\nthis.email = email;
\n}
\n}<\/p>\n
Swagger Codegen \u80fd\u591f\u6839\u636e OpenAPI \u6587\u6863\u81ea\u52a8\u751f\u6210\u591a\u79cd\u8bed\u8a00\u7684\u5ba2\u6237\u7aef SDK \u6216\u670d\u52a1\u7aef\u9aa8\u67b6\u4ee3\u7801，\u51cf\u5c11\u91cd\u590d\u52b3\u52a8\u3002\u4e0b\u9762\u6f14\u793a\u5982\u4f55\u901a\u8fc7\u547d\u4ee4\u884c\u5de5\u5177\u751f\u6210 Java \u5ba2\u6237\u7aef\u4ee3\u7801：<\/p>\n
# \u4f7f\u7528 Docker \u8fd0\u884c Swagger Codegen
\ndocker run –rm -v ${PWD}:\/local swaggerapi\/swagger-codegen-cli-v3 generate \\\\
\n -i \/local\/api-docs.yaml \\\\
\n -l java \\\\
\n -o \/local\/generated-client<\/p>\n
\u751f\u6210\u540e\u7684\u4ee3\u7801\u7ed3\u6784\u5982\u4e0b：<\/p>\n
generated-client\/
\n\u251c\u2500\u2500 build.gradle
\n\u251c\u2500\u2500 settings.gradle
\n\u251c\u2500\u2500 docs\/
\n\u251c\u2500\u2500 src\/
\n\u2502 \u2514\u2500\u2500 main\/
\n\u2502 \u251c\u2500\u2500 java\/com\/example\/client\/
\n\u2502 \u2502 \u251c\u2500\u2500 api\/UserApi.java
\n\u2502 \u2502 \u251c\u2500\u2500 model\/User.java
\n\u2502 \u2502 \u2514\u2500\u2500 …
\n\u2502 \u2514\u2500\u2500 resources\/
\n\u2514\u2500\u2500 README.md<\/p>\n
\u751f\u6210\u7684 UserApi \u7c7b\u5c01\u88c5\u4e86 HTTP \u8bf7\u6c42\u903b\u8f91，\u5f00\u53d1\u8005\u53ea\u9700\u8c03\u7528\u65b9\u6cd5\u5373\u53ef\u5b8c\u6210\u63a5\u53e3\u5bf9\u63a5：<\/p>\n
import com.example.client.ApiClient;
\nimport com.example.client.api.UserApi;
\nimport com.example.client.model.User;
\npublic class Demo {
\npublic static void main(String[] args) {
\nApiClient client = new ApiClient();
\nclient.setBasePath("http:\/\/localhost:8080");
\nUserApi userApi = new UserApi(client);
\n \/\/ \u8c03\u7528\u751f\u6210\u7684\u63a5\u53e3\u65b9\u6cd5
\n User user = userApi.getUserById(1L);
\n System.out.println("\u7528\u6237\u59d3\u540d：" + user.getName());
\n}
\n}<\/p>\n
Swagger Editor \u662f\u4e00\u4e2a\u57fa\u4e8e\u6d4f\u89c8\u5668\u7684\u5728\u7ebf\u7f16\u8f91\u5668，\u652f\u6301\u5b9e\u65f6\u7f16\u5199\u548c\u6821\u9a8c OpenAPI \u6587\u6863\u3002\u5b83\u7279\u522b\u9002\u5408\u5728\u9879\u76ee\u521d\u671f\u5feb\u901f\u8bbe\u8ba1\u63a5\u53e3\u5951\u7ea6\u3002<\/p>\n
\u4f7f\u7528 Swagger Editor \u7684\u5178\u578b\u6d41\u7a0b\u5982\u4e0b：<\/p>\n
\u4e0b\u9762\u662f\u4e00\u4e2a\u5728 Editor \u4e2d\u7f16\u5199\u7684\u7b80\u5316\u793a\u4f8b：<\/p>\n
openapi: 3.0.0
\ninfo:
\n title: \u8ba2\u5355\u670d\u52a1 API
\n version: 0.1.0
\npaths:
\n \/orders:
\n get:
\n summary: \u67e5\u8be2\u8ba2\u5355\u5217\u8868
\n responses:
\n '200':
\n description: \u8fd4\u56de\u8ba2\u5355\u6570\u7ec4
\n content:
\n application\/json:
\n schema:
\n type: array
\n items:
\n $ref: '#\/components\/schemas\/Order'
\ncomponents:
\n schemas:
\n Order:
\n type: object
\n properties:
\n orderId:
\n type: string
\n amount:
\n type: number
\n format: double<\/p>\n
\u5728\u5b9e\u9645\u4f7f\u7528 Swagger \u7684\u8fc7\u7a0b\u4e2d，\u5f00\u53d1\u8005\u5e38\u4f1a\u9047\u5230\u4e00\u4e9b\u95ee\u9898，\u8fd9\u91cc\u603b\u7ed3\u51e0\u6761\u7ecf\u9a8c：<\/p>\n
\u4e0b\u9762\u6f14\u793a\u5982\u4f55\u6309\u6a21\u5757\u5206\u7ec4\u914d\u7f6e\u591a\u4e2a Docket：<\/p>\n
@Configuration
\npublic class MultiGroupSwaggerConfig {
\n@Bean
\npublic Docket userApi() {
\n return new Docket(DocumentationType.OAS_30)
\n .groupName("\u7528\u6237\u6a21\u5757")
\n .select()
\n .apis(RequestHandlerSelectors.basePackage("com.example.controller.user"))
\n .build();
\n}
\n@Bean
\npublic Docket orderApi() {
\nreturn new Docket(DocumentationType.OAS_30)
\n.groupName("\u8ba2\u5355\u6a21\u5757")
\n.select()
\n.apis(RequestHandlerSelectors.basePackage("com.example.controller.order"))
\n.build();
\n}
\n}<\/p>\n
Swagger \u7684\u6838\u5fc3\u7ec4\u4ef6\u5404\u53f8\u5176\u804c：OpenAPI \u89c4\u8303\u5b9a\u4e49\u63a5\u53e3\u5951\u7ea6，Swagger UI \u63d0\u4f9b\u53ef\u89c6\u5316\u5c55\u793a，\u6ce8\u89e3\u9a71\u52a8\u6587\u6863\u81ea\u52a8\u751f\u6210，Codegen \u52a0\u901f\u591a\u7aef\u4ee3\u7801\u4ea7\u51fa，Editor \u8f85\u52a9\u5951\u7ea6\u8bbe\u8ba1\u3002\u638c\u63e1\u8fd9\u4e9b\u7ec4\u4ef6\u7684\u534f\u4f5c\u65b9\u5f0f，\u80fd\u591f\u5e2e\u52a9\u56e2\u961f\u5efa\u7acb\u89c4\u8303\u3001\u9ad8\u6548\u3001\u53ef\u6301\u7eed\u7ef4\u62a4\u7684 API \u6587\u6863\u4f53\u7cfb\u3002\u5e0c\u671b\u672c\u6587\u7684\u4ee3\u7801\u5b9e\u4f8b\u80fd\u4e3a\u8bfb\u8005\u7684\u5b9e\u9645\u9879\u76ee\u63d0\u4f9b\u53c2\u8003\u3002<\/p>\n","protected":false},"excerpt":{"rendered":"
1. \u5f15\u8a00\u5728\u524d\u540e\u7aef\u5206\u79bb\u7684\u5f00\u53d1\u6a21\u5f0f\u4e0b，\u63a5\u53e3\u6587\u6863\u7684\u7ef4\u62a4\u4e00\u76f4\u662f\u4e2a\u75db\u70b9\u3002Swagger \u4f5c\u4e3a\u4e00\u5957\u5f00\u6e90\u7684 API \u6587\u6863\u5de5\u5177\u94fe，\u80fd\u591f\u6839\u636e\u4ee3\u7801\u81ea\u52a8\u751f\u6210\u63a5\u53e3\u6587\u6863，\u5e76\u63d0\u4f9b\u53ef\u89c6\u5316\u7684\u8c03\u8bd5\u754c\u9762，\u6781\u5927\u63d0\u5347\u4e86\u5f00\u53d1\u534f\u4f5c\u6548\u7387\u3002\u672c\u6587\u5c06\u4ece Swagger \u7684\u6838\u5fc3\u7ec4\u4ef6\u5165\u624b，\u7ed3\u5408\u4e30\u5bcc\u7684\u4ee3\u7801\u5b9e\u4f8b，\u5e2e\u52a9\u8bfb\u8005\u6df1\u5165\u7406\u89e3\u5176\u5de5\u4f5c\u539f\u7406\u4e0e\u4f7f\u7528\u65b9\u6cd5\u30022. Swagger \u751f\u6001\u6982\u89c8Swagger \u5e76\u975e\u5355\u4e00\u5de5\u5177，\u800c\u662f\u4e00\u5957\u56f4\u7ed5 OpenAPI<\/p>\n","protected":false},"author":2,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[188],"topic":[],"class_list":["post-93799","post","type-post","status-publish","format-standard","hentry","category-server","tag-188"],"yoast_head":"\n