📌  相关文章
📜  使用自定义注释增强Swagger文档

📅  最后修改于: 2021-01-12 00:58:25             🧑  作者: Mango

使用自定义注释增强Swagger文档

在上一节中，我们了解了API文档。我们看到了Swagger文档的高级概述结构。在本节中，我们将自定义Swagger元素info 。 Swagger注释在swagger-annotations-1.5.20.jar文件中定义。

步骤1：打开SwaggerConfig.java 。

步骤2：创建ApiInfo类型的常量DEFAULT_API_INFO。

private static final ApiInfo DEFAULT_API_INFO = null;

步骤3：按住Ctrl键，然后单击常量类型(ApiInfo)。 ApiInfo类将打开。

步骤4：从类中复制两个常量DEFAULT _CONTACT和DEFAULT。或复制以下代码并将其粘贴到SwaggerConfig.java中。将常量DEFAULT重命名为DEFAULT_API_INFO。

public static final Contact DEFAULT_CONTACT = new Contact("", "", "");
public static final ApiInfo DEFAULT_API_INFO = new ApiInfo("Api Documentation", "Api Documentation", "1.0", "urn:tos", DEFAULT_CONTACT, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());

步骤5：配置开发人员或组织的联系方式。

public static final Contact DEFAULT_CONTACT = new Contact("Andrew", "http://www.javatpoint.com", "demo@javatpoint.com");

步骤6：配置DEFAULT_API_INFO。在此配置中，提供我们要在Swagger文档中显示的所有信息。

public static final ApiInfo DEFAULT_API_INFO = new ApiInfo("RESTful API Demo", "Api Documentation Demo", "1.0", "urn:tos",
DEFAULT_CONTACT, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());

SwaggerConfig.java

package com.javatpoint.server.main;
import java.util.ArrayList;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.VendorExtension;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
//Configuration
@Configuration
//Enable Swagger
@EnableSwagger2
public class SwaggerConfig 
{
//configuring the contact detail
public static final Contact DEFAULT_CONTACT = new Contact("Andrew", "http://www.javatpoint.com", "javatpoint");
//configuring DEFAULT_API_INFO
public static final ApiInfo DEFAULT_API_INFO = new ApiInfo("RESTful API Demo", "Api Documentation Demo", "1.0", "urn:tos",
DEFAULT_CONTACT, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
//creating bean
@Bean
public Docket api()
{
ApiInfo apiInfo;
return new Docket(DocumentationType.SWAGGER_2).apiInfo(DEFAULT_API_INFO);
}
}

步骤7：重新启动应用程序。

步骤8：打开浏览器，然后输入URI http：// localhost：8080 / v2 / api-docs。它在文档中显示了更新的联系方式和API信息。

接受并产生XML格式

我们应该更具体地说明我们的生产和消费。因此，在下一步中，我们将添加内容协商。我们可以接受application / json或application / xml的输入，并以application / json或application / xml格式产生响应。

让我们在项目中指定内容协商。

步骤1：在SwaggerConfig.java中，转到Docket api()并添加.produces(DEFAULT_PRODUCES_AND_CONSUMES).consumes(DEFAULT_PRODUCES_AND_CONSUMES)。

return new Docket(DocumentationType.SWAGGER_2).apiInfo(DEFAULT_API_INFO).produces(DEFAULT_PRODUCES_AND_CONSUMES).consumes(DEFAULT_PRODUCES_AND_CONSUMES);

步骤2：创建一个常量DEFAULT_PRODUCES_AND_CONSUMES 。

private static final Set DEFAULT_PRODUCES_AND_CONSUMES = null;

第3步：创建一个HashSet并添加两个值application / json和application / xml 。

请注意，我们无法将值直接传递给HashSet。因此，我们已经将List传递给HashSet的构造函数。

private static final Set DEFAULT_PRODUCES_AND_CONSUMES = new HashSet(Array.asList("application/json","appication/xml"));

SwaggerConfig.java

package com.javatpoint.server.main;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.HashSet;
import java.util.Set;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.service.VendorExtension;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
//Configuration
@Configuration
//Enable Swagger
@EnableSwagger2
public class SwaggerConfig 
{
//configuring the contact detail
public static final Contact DEFAULT_CONTACT = new Contact("Andrew", "http://www.javatpoint.com", "javatpoint");
//configuring DEFAULT_API_INFO
public static final ApiInfo DEFAULT_API_INFO = new ApiInfo("RESTful API Demo", "Api Documentation Demo", "1.0", "urn:tos",
DEFAULT_CONTACT, "Apache 2.0", "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
//two format which we want to produce and consume
private static final Set DEFAULT_PRODUCES_AND_CONSUMES = new HashSet(Arrays.asList("application/json","appication/xml"));
//creating bean
@Bean
public Docket api()
{
ApiInfo apiInfo;
return new Docket(DocumentationType.SWAGGER_2).apiInfo(DEFAULT_API_INFO).produces(DEFAULT_PRODUCES_AND_CONSUMES).consumes(DEFAULT_PRODUCES_AND_CONSUMES);
}
}

步骤4：打开浏览器，然后输入URI http：// localhost：8080 / v2 / api-docs。

上图显示了它使用并产生JSON和XML格式。

我们可以添加有关用户模型的更多描述，例如出生日期必须是过去的日期，名称必须至少包含五个字符，等等。让我们在用户模型中添加更多描述。

步骤1：打开User.java并在类名上方添加@ApiModel批注。添加有关用户模型的描述。

@ApiModel：它提供了有关Swagger模型的其他信息。

我们添加了以下描述：

@ApiModel(description="All details about the user")

步骤2：在dob变量上方添加另一个注释@ApiModelProperty。

@ApiModelProperty：它允许控制特定于招摇的定义，例如值和其他注释。

@ApiModelProperty(notes="Birth date should be in the past")

步骤3：类似地，为名称变量添加@ApiModelProperty批注。

@ApiModelProperty(notes="name should have atleast 5 characters")

User.java

package com.javatpoint.server.main.user;
import java.util.Date;
import javax.validation.constraints.Past;
import javax.validation.constraints.Size;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
@ApiModel(description="All details about the user")
public class User 
{
private Integer id;
@Size(min=5, message="Name should have atleast 5 characters")
@ApiModelProperty(notes="name should have atleast 5 characters")
private String name;
@Past
@ApiModelProperty(notes="Birth date should be in the past")
private Date dob;
//default constructor    
protected User()
{
    
}
public User(Integer id, String name, Date dob) 
{
super();
this.id = id;
this.name = name;
this.dob = dob;
}
public Integer getId() 
{
return id;
}
public void setId(Integer id) 
{
this.id = id;
}
public String getName() 
{
return name;
}
public void setName(String name) 
{
this.name = name;
}
public Date getDob() 
{
return dob;
}
public void setDob(Date dob) 
{
this.dob = dob;
}
@Override
public String toString() 
{
//return "User [id=" + id + ", name=" + name + ", dob=" + dob + "]";
return String.format("User [id=%s, name=%s, dob=%s]", id, name, dob);
}
}

步骤4：重新启动应用程序。

步骤5：打开浏览器，然后输入URI http：// localhost：8080 / v2 / api-docs。如果我们查看User模型的描述，我们指定的描述会出现在这里。

API文档作为API非常重要。我们服务的使用者应该对如何使用服务，有什么不同的细节，输出的外观等没有任何疑问。使用者应该清楚一切，以便用户可以轻松理解。

因此，Swagger文档对于服务的使用者是有益的。 Swagger提供了许多注释，可用于增强模型，操作和swagger配置。