使用springdoc构建RESTful API文档

在Web应用程序中，RESTful API是一种通用的设计模式，用于设计强大，灵活和易于使用的API。随着微服务和云计算等技术的出现，越来越多的企业使用RESTful API建立自己的应用，使其更具可扩展性和互操作性。

然而，RESTful API不是只需要设计一下就可以轻易实现的。为了使您的API符合一些标准和最佳实践，您需要在您的API文档中提供准确的描述，这就需要你去构建RESTful API文档。在这方面，springdoc是一个非常不错的选择。

一、快速入门

springdoc是一个用于构建RESTful API文档的库。它使用spring-mvc和spring-boot来自动生成文档，并使用OpenAPI（Swagger）规范来编写文档。在本节中，我们将学习如何在您的应用程序中使用springdoc来生成和提供文档。

首先，您需要将springdoc添加到您的Maven项目中：

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

然后，在您的主应用程序类上添加@EnableSwagger2注释：

@EnableSwagger2
@SpringBootApplication
public class MyApp {
    // ...
}

接下来，定义一些RESTful API并为每个API添加说明：

@RestController
public class MyController {
    @GetMapping("/hello")
    @ApiOperation(value = "Say hello", notes = "Just for demo")
    public String hello() {
        return "Hello, world!";
    }
}

您可以在@RequestMapping或@GetMapping注释的URL路径中包含变量。例如：

@GetMapping("/persons/{id}")
@ApiOperation(value = "Get a person", notes = "Get a person by id.")
@ApiResponses(value = {
        @ApiResponse(code = 200, message = "Success"),
        @ApiResponse(code = 404, message = "Not found"),
        @ApiResponse(code = 500, message = "Server error")
})
public Person getPerson(@PathVariable Long id) {
    // ...
}

最后，在应用程序中启动springdoc，并访问网址http://localhost:8080/swagger-ui.html，您将获得自动生成的RESTful API文档。您可以在文档中添加其他的说明和注释。

二、生成规范

springdoc不仅自动生成RESTful API文档，还可以生成OpenAPI规范。

您可以通过在应用程序中设置以下属性来配置生成的规范：

springdoc.swagger-ui.title=My API
springdoc.swagger-ui.description=My API description
springdoc.swagger-ui.version=1.0.0
springdoc.swagger-ui.termsOfServiceUrl=https://example.com/terms
springdoc.swagger-ui.contact.name=My Name
springdoc.swagger-ui.contact.email=myname@example.com
springdoc.swagger-ui.contact.url=https://example.com
springdoc.swagger-ui.license.name=Apache 2.0
springdoc.swagger-ui.license.url=https://www.apache.org/licenses/LICENSE-2.0.html
springdoc.swagger-ui.base-url=/api

您可以使用Swagger Editor对生成的规范进行进一步编辑和自定义。

三、自定义UI

springdoc UI可以通过多种方式进行自定义，以满足您的个性化要求，例如：

• 更改UI颜色，图标和布局
• 在文档中添加注释和说明
• 添加自定义UI元素，例如搜索框，网站地图和其他页面元素
• 支持多语言和Internationalization

您只需按照springdoc UI定制规则创建自己的CSS样式表即可。以下是一个简单的示例：

/* 设置UI颜色 */
.swagger-ui .opblock-post .opblock-summary-method {
    background-color: #4caf50;
    color: #fff;
}

/* 添加注释 */
.swagger-ui .opblock-description {
    font-style: italic;
}

/* 添加搜索框 */
.swagger-ui .topbar-wrapper .download-url-wrapper {
    display: none;
}

.swagger-ui .topbar-wrapper {
    justify-content: space-between;
}

.swagger-ui .topbar .filter {
    display: block;
    width: 240px;
    margin-right: 8px;
    border-radius: 4px;
    border-color: #ddd;
}

如果需要更高级的UI自定义，请参考springdoc UI定制文档。

四、结论

springdoc是一个非常实用的工具，可以帮助您自动生成RESTful API文档，而不需要手动撰写文档。 springdoc还提供了简单易用的界面和多种自定义选项，以满足您的个性化需求。如果您正在使用spring-mvc或spring-boot，那么springdoc是一个值得一试的工具。