添加链接 注册    登录
link管理
链接快照平台
  • 输入网页链接，自动生成快照
  • 标签化管理网页链接
相关文章推荐
精明的蚂蚁  ·  idea的去除转义的复制粘贴 - CSDN文库·  2 月前    · 
眉毛粗的书签  ·  Intel Core i9-11900K ...·  3 月前    · 
心软的马克杯  ·  请问安装DN40（公称直径小于50mm）蒸汽 ...·  6 月前    · 
直爽的柿子  ·  Nginx知识总结·  8 月前    · 
才高八斗的杯子  ·  python - Pip Install ...·  11 月前    · 
link管理  ›  使用SpringDoc生成接口文档 - UJCMS官网
api接口 接口 swagger
https://www.ujcms.com/knowledge/616.html
气势凌人的打火机
1 月前

SpringDoc是用于生成SpringBoot项目API文档的Java库。在代码中使用 swagger-api 注解，即可生成相应的API文档，和JavaDoc非常类似。

SpringDoc基于 Swagger 3 ， Swagger 3 包名为 io.swagger.core.v3 。

Swagger 3 实现了 OpenAPI 3 接口规范，类似 Hibernate 实现 JPA 规范。 Swagger 3 提供了API注解，还提供了 Swagger-ui 用于生成API文档界面，以及其它的基础功能。

SpringDoc的作用主要是将 Swagger 3 和 SpringBoot 结合起来。

快速使用

只需要在 pom.xml 中引入SpringDoc即可。 

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

启动程序后，访问 /swagger-ui/index.html ，就会显示API文档页面。

也可访问 /v3/api-docs ，返回的是API文档的 JSON 结构数据。可以用该数据生成其它风格的API文档页面，比如可以提供给 Apifox 生成API文档。

文档生成的原理是通过扫描源代码中的 Controller ，根据 RequestMapping 和相应方法的参数生成文档。

API注解

上面生成的文档并没有良好的注释，我们可以通过 swagger-api 注解，给接口加上注释。注解的包路径为 io.swagger.v3.oas.annotations 

@Tag(name = "ArticleController", description = "文章接口")
@RestController
public class ArticleController {
    @Operation(summary = "根据文章ID获取文章对象")
    @ApiResponses(value = {@ApiResponse(description = "文章对象")})
    @GetMapping("/article/{id}")
    public Article getArticleById(@Parameter(description = "文章ID", required = true) @PathVariable("id") Integer id) {

  • 类注释：@Tag(name = "ArticleController", description = "文章接口")
  • 方法注释：@Operation(summary = "根据文章ID获取文章对象")
  • 参数注释：@Parameter(description = "文章ID", required = true)
  • 返回值: @ApiResponses(value = {@ApiResponse(description = "文章对象")})
    • 

    OpenAPI规范
    接口文档基于OpenAPI规范，了解OpenAPI规范有助于了解完整接口文档的编写方式。
    

    参考资料：OpenAPI基本结构
    

    上面的注解对应的OpenAPI规范大致如下：
    

    paths:
  /article/{id}:
      summary: 根据文章ID获取文章对象
      parameters:
        - name: id
          in: path
          required: true
          description: 文章ID
          schema:
            type : integer
            format: int32
      responses:
        default:
          description: 文章对象

    实体类注解
    除了对API进行注解，还可对实体类进行注解。同时支持JSR-303注解。
    

    @Schema(description = "文章")
@NotNull(message = "不能为空")
public class Article extends Serializable {
    @Schema(description = "标题")
    private String title;

    文档定义
    定义文档标题、文档版本号等信息。
    

    @OpenAPIDefinition(
    info = @Info(
        title = "UJCMS API",
        description = "UJCMS 接口文档",
        version = "1.0.0"
@Configuration
public class SwaggerConfig {

    也可使用Java代码
    

    @Bean
public OpenAPI openApi() {
    return new OpenAPI().info(new Info().title("UJCMS API").description("UJCMS 接口文档").version("1.0.0"));

    对应的OpenAPI规范：
    

    info:
  title: UJCMS API
  description: UJCMS 接口文档
  version: 1.0.0

    文档分组
    如果接口较多，可以对接口进行分组，方便查看。
    

    @Configuration
public class SwaggerConfig {
     * 前台 API 分组
    @Bean
    public GroupedOpenApi frontendGroup(@Value() {
        return GroupedOpenApi.builder().group("frontend").displayName("前台API")
                .addOpenApiCustomiser(openApi -> openApi.info(new Info().title("UJCMS 前台 API").version("1.0.0")))
                .packagesToScan("com.ujcms.cms.core.web.api")
                .pathsToMatch("/api/**")
                .build();
     * 后台 API 分组
    @Bean
    public GroupedOpenApi backendGroup() {
        return GroupedOpenApi.builder().group("backend").displayName("后台API")
                .addOpenApiCustomiser(openApi -> openApi.info(new Info().title("UJCMS 后台 API").version("1.0.0")))
                .packagesToScan("com.ujcms.cms.core.web.backendapi")
                .pathsToMatch("/api/backend/**")
                .build();

    也可在配置文件中设置分组：
    

    springdoc.group-configs:
  - group: frontend
    displayName: 前台API
    packagesToScan: com.ujcms.cms.core.web.api
    pathsToMatch: /api/**
  - group: backend
    displayName: 后台API
    packagesToScan: com.ujcms.cms.core.web.backendapi
    pathsToMatch: /api/backend/**

    权限认证
    Swagger不仅能够查看文档，还能在线执行API，不仅能说还能练。
    

    很多情况下API需要登录才能执行，这就需要权限认证。
    

    以前面的后台API为例，增加权限认证的方式如下：
    
    private static final String BEARER_AUTH = "bearerAuth";
    @Bean
    public GroupedOpenApi backendGroup() {
        return GroupedOpenApi.builder().group("backend").displayName("后台API")
                .addOpenApiCustomiser(openApi -> openApi.info(new Info().title("UJCMS 后台 API").version("1.0.0")))
                .packagesToScan("com.ujcms.cms.core.web.backendapi")
                .pathsToMatch("/api/backend/**")
                .addOpenApiCustomiser(openApi -> openApi.components(new Components()
                        .addSecuritySchemes(BEARER_AUTH, new SecurityScheme()
                                .type(SecurityScheme.Type.HTTP).scheme("bearer").bearerFormat("JWT"))))
                .addOperationCustomizer((operation, handlerMethod) -> {
                    operation.addSecurityItem(new SecurityRequirement().addList(BEARER_AUTH));
                    return operation;
                .build();

    此时API接口文档处会出现 Authorize 按钮。

    填入 Bearer 内容，即可完成登录。

    参考资料： https://swagger.io/docs/specification/authentication/

    Swagger2 升级 Swagger3

    SpringDoc 配置

    常用配置项：

  • springdoc.api-docs.enabled ：api-docs是否开启。默认开启。
  • springdoc.swagger-ui.enabled : swagger-ui是否开启。默认开启。
  • springdoc.packages-to-scan : API文档的包扫描路径。默认扫描所有包。
  • springdoc.paths-to-match : API文档的包含的请求路径。默认包含所有请求路径。

    • 完整的配置文档： https://springdoc.org/#properties

  • Swagger 文档： https://swagger.io/docs/specification/about/
  • SpringDoc 文档： https://springdoc.org
  • SpringDoc github： https://github.com/springdoc/springdoc-openapi
  • SpringDoc demo： https://github.com/springdoc/springdoc-openapi-demos/tree/master/springdoc-openapi-spring-boot-2-webmvc
    •  
    推荐文章
    精明的蚂蚁  ·  idea的去除转义的复制粘贴 - CSDN文库
    2 月前
    眉毛粗的书签  ·  Intel Core i9-11900K Benchmarks - Geekbench
    3 月前
    心软的马克杯  ·  请问安装DN40（公称直径小于50mm）蒸汽管道，安装单位需要具有相关压力管道资质吗？_芜湖市市场监督管理局
    6 月前
    直爽的柿子  ·  Nginx知识总结
    8 月前
    才高八斗的杯子  ·  python - Pip Install not installing into correct directory? - Stack Overflow
    11 月前
    Link管理   ·   51好读   ·   Sov5搜索   ·   小百科
    link管理 - 链接快照平台