使用自定义注解增强 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<VendorExtension>());

步骤 5： 配置开发人员或组织的联系详细信息。

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

步骤 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<VendorExtension>());

SwaggerConfig.java

package cn.javatiku.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.javatiku.cn", "javatiku");  
//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<VendorExtension>());  
//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 信息。

restful-web-services-enhancing-swagger-documentation.png

接受和生成 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<String> DEFAULT_PRODUCES_AND_CONSUMES = null;

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

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

javaCopy code
private static final Set<String> DEFAULT_PRODUCES_AND_CONSUMES = new HashSet<String>(Arrays.asList("application/json", "application/xml"));

SwaggerConfig.java

package cn.javatiku.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.javatiku.cn", "javatiku");  
//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<VendorExtension>());  
//two format which we want to produce and consume  
private static final Set<String> DEFAULT_PRODUCES_AND_CONSUMES = new HashSet<String>(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： 重新启动应用程序。

步骤 5： 打开浏览器，键入 URI http://localhost:8080/v2/api-docs。

restful-web-services-enhancing-swagger-documentation2.png

上面的图像显示它可以消耗和生成 JSON 和 XML 格式。

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

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

@ApiModel： 它提供有关 Swagger 模型的额外信息。

我们已经添加了以下描述：

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

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

@ApiModelProperty： 它允许控制 Swagger 特定的定义，例如值和额外的注释。

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

步骤 3： 类似地，为 name 变量添加 @ApiModelProperty 注解。

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

User.java

package cn.javatiku.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 模型的描述，我们指定的描述将显示在这里。

restful-web-services-enhancing-swagger-documentation3.png

API 文档与 API 一样重要。我们的服务使用者不应该对如何使用服务，不同的细节，输出是什么样子等有任何疑问。一切都应该对使用者清晰明了，以便用户可以轻松理解。

因此，Swagger 文档对于服务的消费者非常有益。Swagger 提供了许多注解，可以用于增强模型、操作和 Swagger 配置。

标签: spring, Spring教程, Spring语言学习, Spring框架, Spring框架教程, Spring框架高级教程, spring boot, spring boot入门教程, spring boot学习教程, spring boot下载, spring boot框架入门, spring boot面试题, spring boot技术