先决条件

  1. Java 开发人员工具包 8(或更高版本)
  2. 已在开发计算机上安装 Maven
  3. 已在开发计算机上安装 Git
  4. Azure 订阅付费版或试用版
  5. HTTP 测试应用程序,如 Postman

使用 Swagger.IO 创建 API 基架

使用 swagger.io 在线编辑器可以输入表示 API 结构的 Swagger JSON 或 YAML 代码。设计 API 外围应用后,可以针对各种不同的平台和框架导出代码。在下一部分,我们将修改基架代码,包含模拟功能。

本演示从粘贴到 swagger.io 编辑器中的 Swagger JSON 正文开始,接着使用该正文来生成利用 JAX-RS 访问 REST API 终结点的代码。然后,将编辑基架代码来返回模拟数据,以便模拟一个构建在数据持久性机制基础上的 REST API。

  1. 将以下 Swagger JSON 代码复制到剪贴板:

    {
        "swagger": "2.0",
        "info": {
            "version": "v1",
            "title": "Contact List",
            "description": "A Contact list API based on Swagger and built using Java"
        },
        "host": "localhost",
        "schemes": [
            "http",
            "https"
        ],
        "basePath": "/api",
        "paths": {
            "/contacts": {
                "get": {
                    "tags": [
                        "Contact"
                    ],
                    "operationId": "contacts_get",
                    "consumes": [],
                    "produces": [
                        "application/json",
                        "text/json"
                    ],
                    "responses": {
                        "200": {
                            "description": "OK",
                            "schema": {
                                "type": "array",
                                "items": {
                                    "$ref": "#/definitions/Contact"
                                }
                            }
                        }
                    },
                    "deprecated": false
                }
            },
            "/contacts/{id}": {
                "get": {
                    "tags": [
                        "Contact"
                    ],
                    "operationId": "contacts_getById",
                    "consumes": [],
                    "produces": [
                        "application/json",
                        "text/json"
                    ],
                    "parameters": [
                        {
                            "name": "id",
                            "in": "path",
                            "required": true,
                            "type": "integer",
                            "format": "int32"
                        }
                    ],
                    "responses": {
                        "200": {
                            "description": "OK",
                            "schema": {
                                "type": "array",
                                "items": {
                                    "$ref": "#/definitions/Contact"
                                }
                            }
                        }
                    },
                    "deprecated": false
                }
            }
        },
        "definitions": {
            "Contact": {
                "type": "object",
                "properties": {
                    "Id": {
                        "format": "int32",
                        "type": "integer"
                    },
                    "Name": {
                        "type": "string"
                    },
                    "EmailAddress": {
                        "type": "string"
                    }
                }
            }
        }
    }

     

  2. 导航到在线 Swagger 编辑器。在该位置,单击“文件”->“粘贴 JSON”菜单项。
  3. 粘贴前面复制的联系人列表 API Swagger JSON。
  4. 查看编辑器中显示的文档页和 API 摘要。
  5. 择“生成服务器”->“JAX RS”菜单选项,创建服务器端代码的基架,稍后要编辑该代码来添加模拟实现。
  1. 生成代码后,系统会提供要下载的 ZIP 文件。此文件包含 Swagger 代码生成器创建了基架的代码,以及所有关联的生成脚本。将整个库解压缩到开发工作站上的某个目录。
  2. 编辑代码以添加 API 实现

在本部分,将 Swagger 所生成代码的服务器端实现替换为自定义代码。新代码将 Contact 实体的 ArrayList 返回给调用方客户端。

  1. 使用 Visual Studio Code 或偏好的文本编辑器,打开位于 src/gen/java/io/swagger/model 文件夹中的 Contact.java 模型文件。

  2. 将以下构造函数添加到 Contact 类。

    public Contact(Integer id, String name, String email) 
    {
        this.id = id;
        this.name = name;
        this.emailAddress = email;
    }
  3. 使用 Visual Studio Code 或偏好的文本编辑器,打开位于 src/main/java/io/swagger/api/impl 文件夹中的 ContactsApiServiceImpl.java 服务实现文件。

  4. 使用新代码覆盖文件中的代码,将模拟实现添加到服务代码。

    package io.swagger.api.impl;
    
    import io.swagger.api.*;
    import io.swagger.model.*;
    import com.sun.jersey.multipart.FormDataParam;
    import io.swagger.model.Contact;
    import java.util.*;
    import io.swagger.api.NotFoundException;
    import java.io.InputStream;
    import com.sun.jersey.core.header.FormDataContentDisposition;
    import com.sun.jersey.multipart.FormDataParam;
    import javax.ws.rs.core.Response;
    import javax.ws.rs.core.SecurityContext;
    
    @javax.annotation.Generated(value = "class io.swagger.codegen.languages.JaxRSServerCodegen", date = "2015-11-24T21:54:11.648Z")
    public class ContactsApiServiceImpl extends ContactsApiService {
    
        private ArrayList<Contact> loadContacts()
        {
            ArrayList<Contact> list = new ArrayList<Contact>();
            list.add(new Contact(1, "Barney Poland", "barney@contoso.com"));
            list.add(new Contact(2, "Lacy Barrera", "lacy@contoso.com"));
            list.add(new Contact(3, "Lora Riggs", "lora@contoso.com"));
            return list;
        }
    
        @Override
        public Response contactsGet(SecurityContext securityContext)
        throws NotFoundException {
            ArrayList<Contact> list = loadContacts();
            return Response.ok().entity(list).build();
            }
    
        @Override
        public Response contactsGetById(Integer id, SecurityContext securityContext)
        throws NotFoundException {
            ArrayList<Contact> list = loadContacts();
            Contact ret = null;
    
            for(int i=0; i<list.size(); i++)
            {
                if(list.get(i).getId() == id)
                    {
                        ret = list.get(i);
                    }
            }
            return Response.ok().entity(ret).build();
        }
    }

     

  5. 打开命令提示符,将目录切换到应用程序的根文件夹。
  6. 执行以下 Maven 命令生成代码,然后在本地使用 Jetty 应用服务器运行该代码。
    mvn package jetty:run

     

  7. 应会在命令窗口中看到 Jetty 已经在端口 8080 上启动代码。
  8. 使用 Postman 对 http://localhost:8080/api/contacts 中的“get all contacts”API 方法发出请求。
  9. 用 Postman 对 http://localhost:8080/api/contacts/2 中的“get specific contact”API 方法发出请求。
  10. 最后,在控制台中执行以下 Maven 命令来生成 Java WAR(Web 存档)文件。
    mvn package war:war

     

  11. 生成的 WAR 文件将放入 target 文件夹。导航到 target 文件夹,然后将 WAR 文件重命名为 ROOT.war。(请确保大小写符合此格式)。
    rename swagger-jaxrs-server-1.0.0.war ROOT.war

     

  12. 最后,从应用程序的根文件夹执行以下命令创建 deploy 文件夹,用于将 WAR 文件部署到 Azure。
    mkdir deploy
     mkdir deploy\webapps
     copy target\ROOT.war deploy\webapps
     cd deploy

     

考虑到篇幅问题,有兴趣的朋友可以通过这个链接来查看后续步骤。