标签: redoc

OpenAPI 非常适合 RESTful 服务，目前，我正在通过使用POSTa来破解它以用于异步消息系统（特别是 Kafka） /topic，以便我可以使用 redoc 为 API 创建一个网站。

我想看看是否已经为此建立了记录系统。特别是因为GET /events用于事件源的数据日益庞大。

以前在 Django 1.11 中，我以这种方式定义了 Django REST API：

在 url.py 中

url(r'^api/test_token$', api.test_token, name='test_token'),

在 api.py 中

@api_view(['POST'])
def test_token(request):
    # ----- YAML below for Swagger -----
    """
    description: test_token
    parameters:
      - name: token
        type: string
        required: true
        location: form       
    """
    token = request.POST['token']

    return Response("test_token success", status=status.HTTP_200_OK)

现在我要迁移到 Django 3.1.5，我想知道如何使用 Django Rest Framework (DRF) 以相同的方式实现上述目标。在上述特定情况下，POST API“test_token”接受一个参数。并生成像 swagger/redoc 这样的 API 文档（可用于测试 API）

一些注意事项：

• 此处还指出​​ django-rest-swagger 已于 2019 年 6 月弃用django-rest-swagger UI 没有用于 POST 请求正文的表单（基于函数的视图）
• 重要的是要注意，它使用 request.POST（表单数据）作为参数https://www.django-rest-framework.org/tutorial/2-requests-and-responses/
• 在 Django 1.11.x …

我正在使用 django、django drf 和 drf-yasg 来生成编写我的 BE 并生成文档。

我有一个名为 User 的模型和一个用于用户的序列化程序：

class UserSerializer(serializers.ModelSerializer):

    class Meta:
        model = users_models.User
        fields = (users_models.User.first_name.field_name,
                  users_models.User.last_name.field_name,)

我有一些方法 Foo 可以获得两个用户。这是请求的序列化程序的样子：

class FooRequestSerializer(serializers.ModelSerializer):
      first_user = UserSerializer(help_text="first user")
      second_user = UserSerializer(help_text="second user")

当我为此生成一个swagger json方案时，我查看了json和redoc，我看到了：

1. first_user 和 second_user 具有相同的引用名称 ($ref)
2. second_user 和 redoc 的描述为“第一个用户”而不是第二个用户。这是因为描述取自具有第一个用户描述的 $ref。

我注意到如果我确保 ref 名称是不同的，那么 redoc 读起来很好，因为 first_user 和 second_user 得到了他们自己的描述。问题来了，因为我也希望以后能够使用 swagger codegen 来创建 Java 存根，所以解决方案和据我所知，每个不同的 ref 名称都有一个不同的类。理想情况下，我会看到对 foo 的调用类似于

Foo(User first_user, User second_user)

这让我想到了一个问题：

• 如果 first_user 和 second_user 具有相同的引用名称，则 redoc 读取错误并且第二个用户具有第一个用户描述。

• 如果 first_user 和 …

我的 API 文档变得相当大，我想知道是否可以将文件分成openapi.yml单独管理的块，而不是将其全部放在一个文件中，然后让 reDoc（或其他一些工具）将其组合起来，然后生成 HTML 站点。

我负责维护公司API文档。我们的 API 是用 ASP.NET 编写的。我最近改用 Swashbuckle 5.6.0，它运行得很好。

我遇到的问题是这样的：

我们将数据模型分为 Post 数据和 Get 数据，例如WebAccountGetData.cs和WebAccountPostData.cs。创建（POST）和更新（PUT）时可以使用Post数据。

Post 数据类中的大多数（如果不是全部）字段都可以为 null，当调用 API 方法时，存储过程会返回描述缺少/需要哪些字段的错误消息。API 不处理必填字段。

使用可为 null 的字段意味着 Swashbuckle 不会向文档添加必需标志。但我们想根据使用的 Http 方法（Post/Put）来显示某个字段是否为必填字段。

API 密钥是必需参数，因为它不可为空。

我知道我可以使用[Required]System.ComponentModel.DataAnnotations 命名空间中的属性，但这会将必需标志应用于 POST 和 PUT 方法，这是我们不希望的。

理想情况下，我想使用自定义属性，在其中可以指定 Post 或 Put 方法中是否需要某个字段。

public class ApiRequiredAttribute : Attribute
{
  public bool RequiredInPost
  {
    get;
    set;
  } = false;

  public bool RequiredInPut
  {
    get;
    set;
  } = false;
}

然后像这样使用它：

[ApiRequired(RequiredInPost = true)]
public int? ApprovalStatusId
{
  get;
  set; …

有人可以分享一些关于如何使用 ReDoc 和 SpringBoot 框架来实现 API 文档的示例吗？如果有人知道一些 ReDoc + Springboot 的好例子，那将会有很大的帮助。

我的公司使用 Open API Spec 来组织内部 API 的文档，并通过 UI 工具（例如 redoc.ly 或 Swagger）呈现它。API 文档作为私有 git 存储库进行管理，永远不会向公众发布。

私有API文档许可

Swagger 为开源项目提供了很好的示例，例如 MIT、GPL、“Apache 2.0”，但私有 API 文档似乎没有涵盖。

https://spec.openapis.org/oas/latest.html#license-object

{
  "name": "Apache 2.0",
  "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
}

调查

我看到有些人以这种方式指定他们的许可证。

  license:
    - name: unlicensed
    - url: "www.example.com"

问题

私有 API 文档项目的合适许可证是什么？

您通常如何在私有 Open API 文档中表示许可证对象？

使用 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 的方案。然而，现在为每个操作呈现相同的文档字符串，这使得我的文档非常长且冗余。

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

我使用 Swashbuckle 和Redoc来记录我的 ASP.NET Core 2.2 API。实时 ReDoc 演示在顶部有一组部分（例如“简介”），其中包含一些自定义 html。我想在 API 中生成类似的部分，但不知道如何执行。

基本上我有：

services.AddSwaggerGen(c => {
    c.SwaggerDoc(...);
    c.IncludeXmlComments(...);
    c.AddSecurityDefinition("OAuth2", ...);
});

然后：

app.UseReDoc(c => {
    c.SpecUrl = "/swagger/v1/swagger.json";
    c.RoutePrefix = "";
});

我已经浏览了 intellisense 选项以及 Swashbuckle readme和wiki，但找不到生成此类部分的方法。

将 HTML 部分添加到基于 Swashbuckle.AspNetCore.ReDoc 的文档的开头的方法是什么？

我正在从 Django 1.11 --> 3.1.5 进行一些迁移工作

之前使用“rest_framework_swagger”，我可以通过 url.py 中的这个来完成 swagger api 分组

url(r'^api/v9/test_token1$', 
    api.test_token, 
    name='test_token'),

url(r'^api/v9/test_token2$', 
    api.test_token, 
    name='test_token'),

并得到这个（注意它是 v9 组）

但是，我在 Django 3.1.5 url.py 上尝试过使用“drf_yasg”

path('/v2/token_api1', token_api1, name='token_api1'),
path('/v2/token_api2', token_api2, name='token_api2'),

我的 api 定义（请注意我正在使用@api_view）

token = openapi.Parameter('token', openapi.IN_FORM, type=openapi.TYPE_STRING, required=True)
@swagger_auto_schema(
    method="post",
    manual_parameters=[token],
    operation_id="token_api1"
)
@api_view(['POST'])
# this is optional and insures that the view gets formdata
@parser_classes([FormParser])
def token_api1(request):
    token = request.POST['token']    
    return Response("success test_api:" + token, status=status.HTTP_200_OK)


token = openapi.Parameter('token', openapi.IN_FORM, type=openapi.TYPE_STRING, required=True)
@swagger_auto_schema(
    method="post",
    manual_parameters=[token],
    operation_id="token_api2" …