标签: openapi

使用 DRF 记录 API 的内置方式，我能够编写如下所示的文档字符串，并且每个操作都由其相应的行记录：

"""
list:    The list action returns all available objects.
retrieve:The retrieve action returns a single object selected by `id`.
create:  The create action expects the fields `name`, creates a new object and returns it.
"""

我正在切换到该库drf-spectacular，它可以轻松生成符合 OpenAPI 的方案。然而，现在为每个操作呈现相同的文档字符串，这使得我的文档非常长且冗余。

有没有办法只为每个操作呈现文档字符串的相关部分？

我不明白为什么我的其余 api 端点在 openapi/ui 中使用 openliberty 不可见/可执行。openapi/ui 报告“规范中没有定义任何操作！” 我的项目由一个空的应用程序类和一个具有单个端点的简单休息控制器组成：

package sandbox.io.rest;

import jakarta.ws.rs.ApplicationPath;
import jakarta.ws.rs.core.Application;

@ApplicationPath("/api")
public class RestApplication extends Application { }

package sandbox.io.rest;

import static jakarta.ws.rs.core.MediaType.APPLICATION_JSON;

import jakarta.enterprise.context.ApplicationScoped;
import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.Response;

@ApplicationScoped
public class RestController
{
    @GET
    @Path("/system/properties")
    @Produces(APPLICATION_JSON)
    public Response getSystemProperties()
    {
        return Response.ok(System.getProperties()).build();
    }
}

我在 server.xml 中激活了以下功能：

    <featureManager>
        <feature>jakartaee-9.1</feature>
        <feature>microProfile-5.0</feature>
<!--        <feature>restfulWS-3.0</feature> -->
<!--        <feature>jsonp-2.0</feature> -->
<!--        <feature>jsonb-2.0</feature> -->
<!--        <feature>cdi-3.0</feature> -->
<!--        <feature>mpConfig-3.0</feature> -->
<!--        <feature>mpRestClient-3.0</feature> -->
<!--        <feature>mpOpenAPI-3.0</feature> …

我正在尝试为对象属性添加多个示例。我使用的 Swagger-Ui 和 Editor 版本是

'{"swaggerEditor":"3.6.31/g10642b3c-dirty","swaggerUi":{"version":"3.23.0","gitRevision":"g23d7260f","gitDirty":true,"buildTimestamp":"Sat, 29 Jun 2019 19:42:59 GMT","machine":"jenins-swagger-oss"}}'

基于OpenAPI doc，此版本的 swagger UI 和编辑器支持多个示例，但我仍然看到此错误：

Structural error at components.schemas.MainObject.allOf.3.properties.partitionProperty
should NOT have additional properties
additionalProperty: examples
Jump to line 3016

这就是我在属性中添加示例的方式：

    MainObject:
      allOf:
      - $ref: '#/components/schemas/MainObjectLite'
      - type: object
        description: foobar.
        readOnly: true
        required:
          - fooRequired
        properties:
         fooRequired:
            type: string
            description: system only field used for table data indexing
         partitionProperty:
            type: string
            description: foobar
            examples:
              sampleExample:
                value: 2016-03-04T03:00:00
                summary: sample partition

我有以下课程：

class Quiz(BaseModel):
    question: str
    subject: str
    choice: str = Query(choices=('eu', 'us', 'cn', 'ru'))
         

我可以像这样基于此类渲染表单

@api.post("/postdata")
def post_data(form_data: Quiz = Depends()):
    return form_data

如何显示选择字段的下拉列表？

我有一个准系统的 SpringBoot 项目，pom 文件中包含最新的 Springdoc 依赖项（截至撰写本文时）：

<dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.6.13</version>
</dependency>

另外我只有网络启动器依赖项：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

它与 Spring Boot 2.7.5 配合良好。在本地计算机上，我可以访问http://localhost:8080/swagger-ui.html并http://localhost:8080/v3/api-docs重定向到 OpenAPI 资源。但是，一旦我将 Spring Boot 版本更改为 3.0.0 并重新启动应用程序，我只能获得404 NOT FOUND上述两个资源。

有没有人找到一种方法可以使 Spring Boot 3.0.0 工作？

我正在使用 FastAPI 和 OpenAPI/Swagger UI 来查看和测试我的端点。

每次我第一次使用端点时，为了测试它，我必须先单击按钮Try it out，这变得很乏味。

有没有办法让它消失并能够立即测试端点？

尝试了解 OpenAPI 在components/schemas部分 中定义可重用对象或在components/requestBodies它确实是作为请求正文的对象时定义可重用对象之间的区别。

除了分离不是真正域对象的简单请求有效负载之外，还有什么区别吗？为什么我们有不同的schemas、requestBodies和部分responses？

特别是在查看生成的客户端代码时，我发现在 中定义的类schemas和requestBodies.

我试图有一个像这样的端点/services?status=New

status将是 New或者Old

这是我的代码：

from fastapi import APIRouter, Depends
from pydantic import BaseModel
from enum import Enum

router = APIRouter()

class ServiceStatusEnum(str, Enum):
    new = "New"
    old = "Old"


class ServiceStatusQueryParam(BaseModel):
    status: ServiceStatusEnum


@router.get("/services")
def get_services(
  status: ServiceStatusQueryParam = Query(..., title="Services", description="my desc"),
):
    pass #my code for handling this route.....

结果是我收到一个似乎与此问题相关的错误

错误说AssertionError: Param: status can only be a request body, using Body()

然后我找到了这里解释的另一个解决方案。

所以，我的代码将是这样的：

from fastapi import APIRouter, Depends
from pydantic …

我是 Fastify 新手，我正在尝试用它设置 swagger 文档。我正在使用 TypeScript，我发现的所有示例都使用 JavaScript 和require语法。

我尝试尽可能遵循示例，但现在我的文档没有显示/我创建的路线的任何内容。

这是我当前的代码：

import fastifySwagger from '@fastify/swagger';
import fastifySwaggerUi from '@fastify/swagger-ui';
import Fastify from 'fastify';

import { errorBoundary } from './plugins/errorBoundary';

const fastify = Fastify({
  logger: true
});

const port = process.env.PORT || 3003;

// Set custom error handler.
fastify.setErrorHandler(errorBoundary);

// Register @fastify/swagger plugin.
fastify.register(fastifySwagger, {
  openapi: {
    info: {
      title: 'Forest Fire API',
      description: 'Forest Fire API Documentation',
      version: '1.0.0'
    },
    servers: [
      {
        url: 'http://localhost'
      }
    ], …

我升级到 Spring boot 3.0.7 并尝试让我的 Open API (swagger) 再次工作，具有这些依赖项（根据springdoc）：

  <dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-ui</artifactId>
    <version>1.7.0</version>
  </dependency>

  <dependency>
    <groupId>org.springdoc</groupId>
    <artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
    <version>2.1.0</version>
  </dependency>

...但是当我构建我的应用程序时，出现以下错误：

java.lang.IllegalStateException: Failed to introspect Class [org.springdoc.webmvc.api.OpenApiWebMvcResource] from ClassLoader [jdk.internal.loader.ClassLoaders$AppClassLoader@1de0aca6]

...“原因”为：

java.lang.NoClassDefFoundError: javax/servlet/http/HttpServletRequest

当我查看罐子OpenApiWebMvcResource中的内容时，它确实是从而不是org.springdoc:springdoc-openapi-webmvc-core:1.7.0导入的：javaxjakarta

package org.springdoc.webmvc.api;
    
import com.fasterxml.jackson.core.JsonProcessingException;
import io.swagger.v3.oas.annotations.Operation;
import java.util.Locale;
import java.util.Optional;
import javax.servlet.http.HttpServletRequest;
...

那么这是一个问题openapi-webmvc-core，还是我接线有问题？