标签: openapi

我试图将一个大的 yml 分成一堆较小的 yml 文档。我按照David Garcia 提供的示例进行操作，然后使用 OpenAPI CodeGenerator 生成我的模型。OpenAPI Generator 抱怨[BUG] attribute components.schemas.Schema name doesn't adhere to regular expression ^[a-zA-Z0-9.-_]+$. 因此，我尝试通过克隆 David Garcia 的存储库并在本地部署来使用 David Garcia 的示例，但我遇到了相同的错误。我决定在swagger editor中检查它，我遇到了同样的问题，但错误消息显示

Semantic error at components.schemas.$ref
Component names can only contain the characters A-Z a-z 0-9 - . _
Jump to line 25

我正在使用 David Garcia 示例中的 yaml：

Semantic error at components.schemas.$ref
Component names can only contain the characters A-Z a-z 0-9 - . _
Jump to …

我正在为基于 .Net core 6 的 API 生成 Swagger 文档。我有一些错误模型将由我的网关返回。这些不会在我的任何 API 端点中使用/返回。我想将这些模型添加到 Swagger 文档架构集合中。如果我遵循内联方式，我就能够成功添加它们。有没有办法将现有模型包含在 Swagger 架构集合中？

我还想将 webhook 模型和示例包含到模式集合中，而无需通过内联选项。

谢谢你的时间。

我正在写一个swagger规范,我有三个独立的端点.如何在文档中分隔它们？我希望明确区分示例:用户,帖子和其他.所以每个人都有一个CRUD描述,并在swagger UI中显示它看起来像:

USERS
// user specs

POST
// post specs

OTHER
// other specs

了解REST API并遵循https://apihandyman.io/writing-openapi-swagger-specification-tutorial-part-2-the-basics/.

API可以接收两个参数:username和bla,但只有username使用required关键字才需要.这对我来说很有意义.

API将返回firstname,, lastname和username,但仅username在使用required关键字时才需要.这对我来说没有意义.缺少required关键字是否表明有时可能不需要其他两个？影响他们是否有什么影响？

paths:
  /persons/{username}:
    get:
      summary: Gets a person
      description: Returns a single person for its username.
      parameters:
        - name: username
          in: path
          required: true
          description: The person's username
          type: string
        - name: bla
          in: query
          description: bla bla bla
          type: string
      responses:
        200:
          description: A Person
          schema:
            required:
              - username
            properties:
              firstName:
                type: string
              lastName: …

我有一个OpenAPI 3.0规范，我想从中生成一个PDF，以便可以将其提供给最终用户。

当前，诸如swagger-spec-to-pdf或swagger2markup之类的工具仅支持Swagger 2.0，但不支持OpenAPI 3.0。是否可以根据OpenAPI 3.0规范生成PDF，而无需将其转换为Swagger 2.0？

我试图让 Swagger 从属性文件中读取 API 文档，swagger.properties但不能。在@ApiOperation注释中有一个错误说：Attribute value must be constant。有关如何解决此问题并能够从属性文件中读取文档的任何建议？
这是控制器代码：

package com.demo.student.demo.controller;

import com.demo.student.demo.entity.Student;
import com.demo.student.demo.service.StudentService;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.web.bind.annotation.*;

import java.util.List;

@RestController
@RequestMapping(value = "/v1/students")
@Api(description = "Set of endpoints for Creating, Retrieving, Updating and Deleting of Students.")
public class StudentController {
    private final String message;

    public StudentController(@Value("${test.swagger.message}") String message){
        this.message=message;
    }

    @Autowired
    private StudentService studentService;

    @GetMapping
    @ApiOperation(message)
    public List<Student> findAll(){
        return studentService.findAl();
    }

}

而且，如何在@API(description) 的类级别注入一个值？

大家好，我创建并使用了 yaml 的 openAPI，我创建了映射 2 个云函数的端点，这些函数使用路径模板来路由调用，google sdk cli 没有错误。现在我通过 POST 调用，https://myendpointname-3p5hncu3ha-ew.a.run.app/v1/setdndforrefcli/12588/dnd?key=[apikey]因为它是由下面的开放 api 映射的，然后回复我“路径与任何要求 URI 模板都不匹配。”。我不知道为什么端点中的路径模板不起作用我添加了 path_translation: APPEND_PATH_TO_ADDRESS以避免谷歌使用 CONSTANT_ADDRESS 默认值，它在查询字符串中附加 id 与 [云函数名称]?GETid=12588 并覆盖具有相同名称的查询参数。有人可以告诉我如何调试端点或 openAPI 中的错误（端点中有绿色的检查确定图标）？

# [START swagger]
swagger: '2.0'
info:
  description: "Get data "
  title: "Cloud Endpoint + GCF"
  version: "1.0.0"
host: myendpointname-3p5hncu3ha-ew.a.run.app
# [END swagger]
basePath: "/v1"
#consumes:
#  - application/json
#produces:
#  - application/json
schemes:
  - https
paths:
  /setdndforrefcli/{id}/dnd:
    post:
      summary: 
      operationId: setdndforrefcli
      parameters:
       - name: id         # is the id parameter …

Springdoc 自动为所有处理程序方法生成 API 文档。即使没有 OpenAPI 注释。

如何从 API 文档中隐藏端点？

我正在尝试在数组中添加一个对象，但这似乎是不可能的。我尝试了以下方法，但总是出现错误：

不允许使用属性名称。

这适用于devices数组中定义的所有项目。如何在 OpenAPI 中定义数组中的项目？

  /demo/:
    post:
      summary: Summary
      requestBody:
        description: Description.
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                Name:
                  type: string
                Number:
                  type: array
                  items:
                    type: string
                description:
                  type: string
                type:
                  type: string
                devices:
                  type: array
                  items:
                    Name:
                      type: string
                    descripiton:
                      type: string
                    Number:
                      type: integer
                    enabled:
                      type: boolean
              required:
                - Name
                - Number
                - devices
      responses:
        '201': # status code
          description: Created.
        '500':
          description: Error.
        '405':
          description: Invalid body has been presented.

如何使用drf-yasg包将示例响应（openapi doc）添加到我的 swagger 文档中？