openapiswagger详解

一、openapiswagger简介

OpenAPI Specification (OAS)是一种编程语言和框架不可知的API描述格式，用于RESTful Web服务。它被设计为用于人工和机器读取，并且具有易于学习的简洁语言，具有已经得到广泛接受的基础模式。

Swagger是支持OAS的开源软件项目，它包含一系列工具和库，可帮助开发人员设计、构建、文档化和使用RESTful Web服务。

OpenAPI Swagger是Swagger的前身，它是一个凭借着Swagger框架而形成的API文档规范。OpenAPI Swagger是一种容易阅读和理解的API开发规范，可以改进API的构建和文档过程，使与API相关的所有方面（如样式、参数、返回值等）都有一个标准的格式化规范。

二、openapiswagger的优势

1、标准的API描述格式

OpenAPI is a standard, which means that it defines a set of constructs that are used to describe RESTful APIs in a consistent way. This standard helps make your API more understandable and easier to use for developers, regardless of the programming language they are using or whether they are using a human-readable or machine-readable format to describe your API.

2、提高Api的质量

OpenAPI Swagger支持自动化API文档生成，可以提高API的质量并减少文档编写时间。

3、可视化API的可用性

OpenAPI Swagger可以通过可视化界面显示API的定义，以增加API的可用性，更好地展示API的重要组件（如请求和响应参数）。

4、支持多种编程语言

OpenAPI Swagger支持多种编程语言，包括Java、Python、JavaScript、PHP等，使得多个编程团队可以同时使用OpenAPI Swagger来构建和文档化API。

三、openapiswagger的基本用法

下面是一个简单的OpenAPI Swagger文档的例子：

{
    "swagger": "2.0",
    "info": {
        "title": "PetStore API",
        "version": "1.0.0"
    },
    "host": "petstore.swagger.io",
    "basePath": "/v1",
    "schemes": [
        "http"
    ],
    "paths": {
        "/pets": {
            "get": {
                "summary": "Returns all pets",
                "responses": {
                    "200": {
                        "description": "A list of pets",
                        "schema": {
                            "type": "array",
                            "items": {
                                "$ref": "#/definitions/Pet"
                            }
                        }
                    }
                }
            }
        }
    },
    "definitions": {
        "Pet": {
            "type": "object",
            "properties": {
                "name": {
                    "type": "string"
                },
                "age": {
                    "type": "number"
                }
            }
        }
    }
}

这个文档描述了一个PetStore API，包括API的基本信息（标题、版本、域名、基本路径、协议类型）和API的路径、请求和响应信息、模型定义等。可以在Swagger UI中查看这个文档。

四、openapiswagger的高级用法

1、参数校验

OpenAPI Swagger支持参数校验，可以增强API的安全性和可用性。例如，可以使用minLength和maxLength属性限制输入字符串的长度并防止注入攻击：

"parameters": [
        {
            "name": "username",
            "in": "query",
            "description": "Username to use for login",
            "required": true,
            "type": "string",
            "minLength": 5,
            "maxLength": 16
        },
        {
            "name": "password",
            "in": "query",
            "description": "Password to use for login",
            "required": true,
            "type": "string",
            "minLength": 5,
            "maxLength": 16,
            "pattern": "^[a-zA-Z0-9]+$"
        }
    ]

2、身份验证

OpenAPI Swagger支持API权限管理和身份验证。例如，可以在API请求中添加Authorization头来验证用户的身份：

"securityDefinitions": {
        "oauth2": {
            "type": "oauth2",
            "flow": "implicit",
            "authorizationUrl": "https://example.com/oauth2/authorize",
            "scopes": {
                "read": "Grants read access",
                "write": "Grants write access",
                "admin": "Grants admin access"
            }
        }
    },
    "security": [
        {
            "oauth2": [
                "read",
                "write"
            ]
        }
    ]

3、自定义页面

OpenAPI Swagger支持定制AP页面。例如，可以添加自定义CSS文件和包含企业品牌的自定义页面：

"swaggerUi": {
        "css": "/my-custom-css.css"
    },
    "info": {
        "x-logo": {
            "url": "https://example.com/logo.jpg",
            "altText": "My custom logo"
        }
    }

五、总结

OpenAPI Swagger是一种API开发规范和工具链，可以提高API的开发效率和可用性，并且支持参数校验、身份验证和自定义页面等高级功能。有了OpenAPI Swagger，API开发和文档化将更加简单、标准和可靠。