标签: api-doc

我创建了一个带有yaml文件的swagger文档:

 api/swagger/swagger.yaml

现在我想与它的定义共享一个静态的html文档,但是在swagger项目中已经说过,他们根本不打算支持html生成.

如何从swagger项目生成静态html文件？

我们基于Azure功能构建了API，并且所有API都是基于Python的。我知道 APIM 提供了一种导入 Azure 函数以及创建和管理 API 的好方法。然而，我正在为开发人员寻找一种轻便快速的解决方案，以便他们可以相互合作。

Swagger 在 Java 生态系统中非常流行，我们只需添加一些注释即可在 Spring Boot 应用程序中使用。

对于用 Python 编写的 Azure 函数，是否有类似的功能可用。我的最终目标是通过某些端点公开 API 文档，以便不同的团队（API 生产者和消费者）可以高效工作，而无需经过融合等

我有一些用普通旧快递写的私人api.是时候把它拿出来并提供一些api文档.

我不想(至少还有)重写我的快速应用程序以将api文档集成到代码中.主要是因为我不确定使用什么框架或规范来记录我的api我真的不想锁定一个特定的东西.

我想在我的api下提供doc作为子资源的一部分(即我不想运行不同的服务器或子域).也许'/ api/docs'.一个加号也可以是我可以嵌入我的应用程序中的UI,可以解析文档,至少在html中提供一个很好的文档演示(api交互是一个加号).

像swagger-node这样的东西很酷,但需要我重新编写所有快速代码以集成swagger.在那一点上,我有一笔巨大的投资,并且与swagger紧密相连.

有没有办法服用swagger或iodocs或者其他东西以对现有路线微创的方式记录我的api？

编辑:

我可以用手写的文档提供Swagger规范.我看到的问题是你必须basePath在swagger doc中定义.这实际上不允许我在不同的域下轻松部署.

如果类实现了接口中定义的方法,则可以选择是复制文档还是引用它<see cref="..." />.

public interface IPerformer
{
    /// <summary>
    /// Do something useful.
    /// </summary>
    /// <param name="something">Object to do something with</param>
    void Do(Something something);
}

public class Implementation : IPerformer
{
    /// <copy from="IPerformer" /> # that is what I want!
    public void Do(Something something)
    {
        // implementation ...
    }
}

是否有可能让API文档工具(Sandcastle)自动复制文档(什么会使阅读API文档更加舒适)？@inheritDoc来自Java Doc的东西？

我使用的是最新版本的Swashbuckle 5.1.3,并注意到有一个新属性SwaggerResponse允许您记录每个响应代码的响应类型.例如:

(https://github.com/domaindrivendev/Swashbuckle/issues/175 <可能证明是有用的).

/// <summary>
/// Lovely.
/// </summary>
/// <param name="blah">Blah blah blah.</param>
/// <returns>Something special.</returns>
/// <response code="200">OK very nice.</response>
/// <response code="400">Invalid request.</response>
[SwaggerResponse(HttpStatusCode.OK, "A", typeof(Foo))]
[SwaggerResponse(HttpStatusCode.BadRequest, "B", typeof(Bar))]
public IHttpActionResult Get(string blah)
{
    // Some code
}

初始响应类记录正确,但在显示表的情况下进一步向下"Response Messages",响应模型为空(对于400 Bad Request).无法在屏幕上看到记录其他响应类型的任何位置.

我一个接一个地遵循了Spring Rest Doc的入门指南,但我无法从生成的片段中获取任何html.

片段在我配置的目录(build/generated-snippets)中生成正常,但我看不到任何html5 /目录,其中包含从片段生成的html文件.

doc 在某些方面说明了如何将文档打包到jar中,很明显它需要一些html5 /目录中的文件,但是在构建运行时不会创建:

dependsOn asciidoctor
from("${asciidoctor.outputDir}/html5") {
    into 'static/docs'
}

我错过了什么？

我的项目文件build.gradle:

buildscript {
    repositories {
        mavenCentral()
    }
    dependencies {
        classpath 'org.springframework.boot:spring-boot-gradle-plugin:1.3.5.RELEASE'
    }
}

plugins {
    id 'org.asciidoctor.convert' version '1.5.2'
}

apply plugin: 'java'
apply plugin: 'eclipse'
apply plugin: 'spring-boot'
apply plugin: 'jacoco'
apply plugin: 'war'

sourceCompatibility = 1.8
targetCompatibility = 1.8

ext { 
    snippetsDir = file('build/generated-snippets')
}

repositories {
    mavenCentral()
}

dependencies {
    compile 'org.springframework.boot:spring-boot-starter-web:1.3.5.RELEASE'
    compile 'org.springframework.boot:spring-boot-starter-logging:1.3.5.RELEASE' …

我试图通过apidoc生成一个 API 文档

如果我的回应是一个数组

[
   {"id" : 1, "name" : "John"},
   {"id" : 2, "name" : "Mary"}
]

我怎么能在@apiSuccess 中设置？

我尝试过 Object[] 但不知道如何设置字段名称。谢谢。

我正在使用 Swagger 2.0 来生成文档。在我的控制器类中，我有一些操作，例如：

public Page<Employee> getEmployees(Pageable pageable) {....}

为响应上述操作而生成的 Swagger 文档：

"responses" : {
          "200" : {
            "schema" : {
              "$ref" : "#/definitions/Page"
              } 
            }
          }

在这里，Swagger 文档没有说响应是Page<Employee>. 如何在 Swagger 的文档中获取泛型数据？

如果我有以下返回类型怎么办？

Page<String,Employee>
Page<Employee,List<Department>>
Page<Employee,Tuple.Two<String,User>>

Swagger 操作参数和模型属性也是如此。

我想修改Django REST Swagger生成的Swagger文档.我想找到Django REST Swagger生成的API定义或模式文件.我一直无法找到这些文件.

当Django REST Swagger创建API文档时,是否会生成类似YAML或JSON文件的内容？

我在哪里可以在服务器上找到该文件？

谢谢!

我可以使用https://github.com/TypeStrong/typedoc创建 REST API 文档，例如https://apidocjs.com/吗？

欢迎提供有关如何重用 TypeScript 类型来生成 REST API 文档的任何建议（使用 Next.js）