在这篇文章中，我们将带领您了解如何将Swagger文档的@ApiModelProperty数据类型设置为String的全貌，包括swaggerapi文档的相关情况。同时，我们还将为您介绍有关@ApiM

在这篇文章中，我们将带领您了解如何将Swagger文档的@ApiModelProperty数据类型设置为String的全貌，包括swagger api文档的相关情况。同时，我们还将为您介绍有关@ApiModelProperty 注解的 required 属性改为 true 之后，swagger 页面一直显示 false、@ApiModelProperty用法、@ApiModel和@ApiModelProperty注解的最佳实践、api – 如何将swagger ui嵌入网页？的知识，以帮助您更好地理解这个主题。

• 如何将Swagger文档的@ApiModelProperty数据类型设置为String（swagger api文档）
• @ApiModelProperty 注解的 required 属性改为 true 之后，swagger 页面一直显示 false
• @ApiModelProperty用法
• @ApiModel和@ApiModelProperty注解的最佳实践
• api – 如何将swagger ui嵌入网页？

如何将Swagger文档的@ApiModelProperty数据类型设置为String（swagger api文档）

我正在使用Spring MVC（通过Spring Boot），并使用swagger-spring-mvc库集成了Swagger API文档。

我有一堂课，看起来像这样：

@ApiModelpublic class CartItem {    ...    private Money listPrice; // joda money class    @JsonSerialize(using = ToStringSerializer.class)    @ApiModelProperty(required = true, dataType = "java.lang.String")    public Money getListPrice() {        return listPrice;    }    ...}

由于我在此字段中使用ToStringSerializer，因此它将在JSON中返回listPrice.toString，换句话说：

{    "listPrice": "USD 10.50"}

但是，昂首阔步的文档不支持dataType =“ java.lang.String”。它将响应模型显示为：

"CartItem": {    "description": "",    "id": "CartItem",    "properties": {        "listPrice": {            "required": false,            "type": "Money"        }    }}

我尝试将@ApiModelProperty批注以及该方法添加到该字段上，在两种情况下，该required字段均受尊重，但该dataType字段将被忽略。我也曾尝试对数据类型使用“字符串”，“字符串”和“
java.lang.String”，但这些都不起作用。

我是否缺少某些东西，或者这仅仅是swagger-spring-mvc库中的错误？

答案1

事实证明，dataType在当前版本的Swagger Spring MVC库中，这完全被忽略了。我在这里找到了简短的讨论：

https://github.com/springfox/springfox/issues/602

看起来一旦发布就可以将其包含在版本2中。

编辑：尽管版本2表示它支持dataType，但目前似乎无法正常工作。满足我需求的更好方法是使用直接模型替换来配置文档设置，如下所示：

@Beanpublic Docket swaggerSpringMvcPlugin() {    return new Docket(DocumentationType.SWAGGER_2)            .directModelSubstitute(Money.class, String.class);}

@ApiModelProperty 注解的 required 属性改为 true 之后，swagger 页面一直显示 false

@ApiModelProperty 注解的 required 属性改为 true 之后，swagger 页面一直显示 false

参考网址:

https://gitee.com/xiaoym/knife4j/issues/ILNDH

具体原因是底层 json 序列化的问题，改起来就很麻烦

https://gitee.com/xiaoym/swagger-bootstrap-ui-demo/tree/master

具体参考 knife4j-lower-spring-boot-demo 这个项目

具体解释

因为在 swagger 的响应 json 中，针对 @Requestbody 这一类型的注解，实体属性只用 @ApiModelProperty 时，基础的类 io.swagger.models.properties.property 接口中，getRequired () 方法加上了 jackson 的 @JsonIgnore 注解，也就是说出来的属性字段，required 字段是忽略的。swagger 响应 json 使用的是 jackson

一种办法是将 swagger-models 的 jar 包中把 @JsonIgnore 注解去掉，但这并非长久之计

问题在线

最近项目使用 swagger+knife4j 作为在线接口文档

但是使用 @RequestBody 传 json 时候，实体类属性上 @ApiModelProperty 注解的 Required 属性失效

解决方案

直接使用 knife4j, 写个配置类，更加轻量级

具体参考 https://gitee.com/xiaoym/swagger-bootstrap-ui-demo/tree/master 的 knife4j-lower-spring-boot-demo 项目

步骤

1. 去除项目中原有的 swagger 和 knife4j 依赖配置

2. 添加低版本的 knife4j 依赖

<dependency>
			<groupId>com.github.xiaoymin</groupId>
			<artifactId>knife4j-spring-boot-starter</artifactId>
			<version>2.0.4</version>
		</dependency>

3. 写 knife4j 配置类

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.*;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;


@Configuration
@EnableSwagger2
public class SwaggerConfiguration {
   


    @Bean(value = "defaultApi2")
    public Docket defaultApi2() {
   
        Docket docket=new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("低版本版本")
                .select()
                .apis(RequestHandlerSelectors.basePackage("xxx.**.controller"))
                //.apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build();
        return docket;
    }
    private ApiInfo apiInfo() {
   
        return new ApiInfoBuilder()
                .title("swagger-bootstrap-ui-demo RESTful APIs")
                .description("# swagger-bootstrap-ui-demo RESTful APIs")
                .termsOfServiceUrl("http://www.xx.com/")
                .contact("xx@qq.com")
                .version("1.0")
                .build();
    }

}

4. 配置在线文档的包路径，在 knife4j 配置类里面进行配置

 .apis(RequestHandlerSelectors.basePackage("xxx.**.controller")) ---->指定controller的包路径

@ApiModelProperty用法

@ApiModelProperty()用于方法，字段； 表示对model属性的说明或者数据操作更改 
value–字段说明 
name–重写属性名字 
dataType–重写属性类型 
required–是否必填 
example–举例说明 
hidden–隐藏

@ApiModel(value="user对象",description="用户对象user")
public class User implements Serializable{
    private static final long serialVersionUID = 1L;
     @ApiModelProperty(value="用户名",name="username",example="xingguo")
     private String username;
     @ApiModelProperty(value="状态",name="state",required=true)
      private Integer state;
      private String password;
      private String nickName;
      private Integer isDeleted;

      @ApiModelProperty(value="id数组",hidden=true)
      private String[] ids;
      private List<String> idList;
     //省略get/set
}

@ApiModel和@ApiModelProperty注解的最佳实践

在现代软件开发中，提供清晰全面的 API 文档 至关重要。@ApiModel 和 @ApiModelProperty 这样的代码注解在此方面表现出色，通过增强模型及其属性的元数据来丰富文档内容。它们的主要功能是为这些元素命名和描述，使生成的 API 文档更加明确。

@ApiModel 和 @ApiModelProperty 的实际用例

这些注解不仅仅是为了展示；它们在各种情景中都发挥着实际的作用：

• 文档生成：通过这些注解整合模型名称、描述和属性详情，可以简化准确详细的 API 文档编制工作。
• 验证：利用 @ApiModelProperty 可以定义验证约束，如最大长度或最小值，帮助确保数据的完整性。
• 模型解读：在生成的 API 指南中，@ApiModel 和 @ApiModelProperty 提供的信息有助于明确展示模型，包括示例和详细描述。

注解应用指南

@ApiModel 的注解用法如下：

另一方面，@ApiModelProperty 的使用注解如下：

实践案例

考虑在一个用户管理系统中的用户模型，需要为其 API 提供清晰的定义。通过为我们的 User 类添加 @ApiModel 注解，以及用 @ApiModelProperty 描述每个属性，我们大大提高了文档的清晰度，使其对开发人员和用户更易于理解。

import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
​
@ApiModel(value = "User", description = "用户模型")
public class User {
    @ApiModelProperty(value = "用户ID", example = "1")
    private Long id;
    
    @ApiModelProperty(value = "用户名", example = "john.doe")
    private String username;
    
    @ApiModelProperty(value = "年龄", example = "25")
    private Integer age;
    
    // 省略其他属性的getters和setters
​
    public Long getId() {
        return id;
    }
​
    public void setId(Long id) {
        this.id = id;
    }
​
    public String getUsername() {
        return username;
    }
    
    public void setUsername(String username) {
        this.username = username;
    }
​
    public Integer getAge() {
        return age;
    }
​
    public void setAge(Integer age) {
        this.age = age;
    }
}

这些注解确保了 API 文档有效地反映了模型及其属性，展示了名称、描述、类型和示例值。这种方法直接导致了一个界定清晰、易于使用的 API 参考资料。

关键注意事项

• 集成相关的 Swagger 依赖并正确配置。
• 注解必须准确定义属性，如名称、描述和数据类型。
• 确保使用 @ApiModelProperty 的属性可以公开访问，并拥有适当的 getter 和 setter 方法。

关于注解使用的常见问题解答

问1：是否可以在一个模型上使用多个 @ApiModel 注解？

答1：不可以，一个模型应该有一个 @ApiModel 注解。

问2：一个属性上可以应用多个 @ApiModelProperty 注解吗？

答2：虽然一个属性可以有多个 @ApiModelProperty 注解，通常是为了提供不同的描述和设置。

与 Apifox 整合简化 API 管理

尽管 Swagger 很有用，但它使用起来可能比较麻烦，缺乏一些协作安全功能。因此，许多人转向使用 Apifox 的 IDEA 插件，以获得更强的功能和方便。它允许在 IDEA 中自动同步 Swagger 注解到 Apifox，并通过多端同步方便测试和维护。

详细使用教程 ：如何使用 Apifox 自动生成 API 接口文档 - 一份详细指南

知识扩展：

• Swagger 注解 @ApiResponses 和 @ApiResponse 的用法
• Swagger 注解 @ApiImplicitParams 和 @ApiImplicitParam 的用法

参考链接：

• Swagger 官方文档：https://swagger.io/docs/specification/data-models/
• SpringFox 官方文档：https://springfox.github.io/springfox/docs/current/

api – 如何将swagger ui嵌入网页？

swagger-ui.css
swagger-ui-bundle.js
swagger-ui-standalone-preset.js

<link rel="stylesheet" type="text/css" href="swagger-ui.css">

<div id="swagger-ui"></div>

<script src="swagger-ui-bundle.js"></script>
<script src="swagger-ui-standalone-preset.js"></script>

<script>
window.onload = function() {
  const ui = SwaggerUIBundle({
    url: "https://yourserver.com/path/to/swagger.json",dom_id: '#swagger-ui',presets: [
      SwaggerUIBundle.presets.apis,SwaggerUIStandalonePreset
    ]
  })

  window.ui = ui
}
</script>

今天关于如何将Swagger文档的@ApiModelProperty数据类型设置为String和swagger api文档的讲解已经结束，谢谢您的阅读，如果想了解更多关于@ApiModelProperty 注解的 required 属性改为 true 之后，swagger 页面一直显示 false、@ApiModelProperty用法、@ApiModel和@ApiModelProperty注解的最佳实践、api – 如何将swagger ui嵌入网页？的相关知识，请在本站搜索。