swagger 微服务

In previous posts we learned how to create a microservice in a notebook using the Jupyter kernel gateway. This will be the foundation for today’s post where we will be creating a notebook microservice with Swagger, a set of tools for representing REST APIs. With this this approach, notebook authors can create and deploy APIs that are easy-to-comsume by other developers.

在以前的文章中，我们学习了如何使用Jupyter内核网关在笔记本中创建微服务。 这将是今天这篇文章的基础，我们将使用Swagger创建笔记本微服务， Swagger是一套用于表示REST API的工具。 使用这种方法，笔记本作者可以创建和部署其他开发人员易于使用的API。

There are many components to Swagger, but today we will be using three. The first component, the Swagger Specification, is a specification we will use to describe out microservice. The second is a code generation plugin to generate our notebook. And finally, we will use the Swagger UI to interact with our newly deployed service.

Swagger有很多组件，但是今天我们将使用三个组件。 第一个组件Swagger规范是我们将用来描述微服务的规范。 第二个是用于生成笔记本的代码生成插件。 最后，我们将使用Swagger UI与我们新部署的服务进行交互。

设置和介绍 (Setup and Introduction)

There is some initial setup needed for this demo:

该演示需要一些初始设置：

While all of that is installing, let’s look at reasons for integrating Swagger in our microservice workflow.

在所有这些安装之后，让我们看一下将Swagger集成到我们的微服务工作流程中的原因。

• Clear API Definition – The Swagger Specification is a standard way for describing our microservice API. This allows for the rapid and collaborative design of what our API will look like.
• Quick Code Generation – Using a standard way to describe our microservice opens up a suite of tools for generating code. Today we will generate a notebook, but there are also tools for generating other client and server side pieces of code.
• Easy API Testing – Another advantage of describing our microservice in a standard way is the use of tools for testing. An example of this is the Swagger UI, which we will use today, for manually verifying the behavior of API endpoints.

• 清晰的API定义 – Swagger规范是描述我们的微服务API的标准方法。 这样可以快速，协作地设计我们的API外观。
• 快速代码生成 –使用一种标准的方式来描述我们的微服务，从而打开了一套用于生成代码的工具。 今天，我们将生成一个笔记本，但是还有一些工具可用于生成其他客户端和服务器端代码。
• 轻松进行API测试 –以标准方式描述我们的微服务的另一个优势是使用测试工具。 一个示例是Swagger UI，我们今天将使用它来手动验证API端点的行为。

设计微服务 (Designing The Microservice)

Our microservice will be used to create and get random quotes. Our service is defined by the following API endpoints:

我们的微服务将用于创建和获取随机报价。 我们的服务由以下API端点定义：

• An endpoint to display random quote
• An endpoint to add new quotes
• And endpoint to get a quote
• An endpoint to update a quote

• 显示随机报价的端点
• 端点以添加新报价
• 和端点获取报价
• 端点更新报价

We now need a way to describe this API so Swagger can generate a specification for us. I used the Swagger Editor to design this API in YAML. The code snippet below is the definition for the full API specification.

现在，我们需要一种描述此API的方法，以便Swagger可以为我们生成规范。 我使用Swagger编辑器在YAML中设计了此API。 以下代码段是完整API规范的定义。

With the microservice defined, we can export it to a JSON file. You can do this in the Swagger Editor by going to File -> ‘Download JSON’.

定义了微服务后，我们可以将其导出到JSON文件。 您可以在Swagger编辑器中执行此操作，方法是转到文件->'下载JSON'。

生成笔记本 (Generating The Notebook)

Once you have the JSON file describing the microservice, navigate to the kernel gateway demos project on your system. You will need to open a command line utility here and go to the directory swagger–notebook–service/jupyter–swagger–codegen. From this directory we will generate the notebook to implement our microservice. The language for the generated notebook defaults to Python 3. You can generate the notebook with the following command:

拥有描述微服务的JSON文件后，导航至系统上的内核网关演示项目。 您将需要在这里打开命令行实用程序，并转到目录招摇 - 笔记本 - 服务 / jupyter - 招摇 - CODEGEN。 从该目录中，我们将生成笔记本以实现我们的微服务。 生成的笔记本的语言默认为Python3。您可以使用以下命令生成笔记本：

path/to/swagger.json  is the JSON file you downloaded earlier from the Swagger Editor. If you did not create your own swagger.json file, use this url to download a completed copy. The command should have generated the following files in target/swagger/python3/WordsOfWisdom/src/:

路径 / 到 / 招摇 。 json是您先前从Swagger编辑器下载的JSON文件。 如果您没有创建自己的swagger.json文件，请使用此URL下载完整的副本。 该命令应该已经在target / swagger / python3 / WordsOfWisdom / src /中生成了以下文件：

• WordsOfWisdomApi.ipynb – The notebook where the service will be implemented
• package.sh – Bundles the notebook with the kernel gateway into a Docker container
• run.sh –  Runs the Docker container built by package.sh
• Dockerfile – A Dockerfile that defines Docker container image

• WordsOfWisdomApi.ipynb –将在其中实现服务的笔记本
• package.sh –将带有内核网关的笔记本捆绑到Docker容器中
• run.sh –运行由package.sh构建的Docker容器
• Dockerfile –定义Docker容器映像的Dockerfile

创作和运行微服务 (Authoring And Running The Microservice)

For the sake of brevity, there is a sample notebook with the implemented API endpoints. You can download this file and put the contents into the   WordsOfWisdomApi.ipynb file.

为简洁起见，这里有一个示例笔记本，其中包含已实现的API端点。 您可以下载此文件，并将内容放入WordsOfWisdomApi中 。 ipynb文件。

From here you can build and deploy the microservice locally with Docker by running:

在这里，您可以通过运行以下命令使用Docker在本地构建和部署微服务：

When everything is built correctly, you should see output similar to the following:

一切构建正确后，您应该会看到类似以下的输出：

With the service successfully running, you will be able to access the API endpoints. Use the ip address for your Docker host and go to:  http://YOUR_DOCKER_HOST:8888/random. This endpoint will display a random quote, served from our notebook.

服务成功运行后，您将能够访问API端点。 使用您的Docker主机的IP地址并转到： http ： // YOUR_DOCKER_HOST：8888 / random 。 该端点将显示一个随机报价，由我们的笔记本提供。

消耗Swagger规格 (Consuming The Swagger Spec)

Our final step will be to use the Swagger UI to interact with our API. The kernel gateway will automatically generate a simple Swagger Specification for consumption through the Swagger UI. The specification can be found at  http://YOUR_DOCKER_HOST:8888/_api/spec/swagger.json. You will need to enter the spec URL into the Swagger UI. The picture below shows how to use the Swagger UI to make requests to the microservice.

Note: The generated swagger spec is still under development and you will not be able to interact with all endpoints. As a temporary alternative, you can use the

我们的最后一步将是使用Swagger UI与我们的API进行交互。 内核网关将自动生成一个简单的Swagger规范，以通过Swagger UI进行使用。 可以在http ： // YOUR_DOCKER_HOST ： 8888 / _api / spec / swagger.json中找到该规范。 您将需要在Swagger UI中输入规范URL。 下图显示了如何使用Swagger UI向微服务发出请求。 注意：生成的swagger规范仍在开发中，您将无法与所有端点进行交互。 作为临时替代方案，您可以使用Swagger编辑器与微服务进行交互。 如果您有需求，欢迎提出要求和问题 。

摘要 (Summary)

In this post you have seen how integrating Swagger into the microservice workflow has helped our development process. If you have any questions or want to get involved with the kernel gateway visit our github repo.

在本文中，您了解了将Swagger集成到微服务工作流程中如何帮助我们的开发过程。 如果您有任何疑问或想参与内核网关，请访问我们的github存储库 。

学到更多 (Learn More)

Lull3rSkat3r

Lull3rSkat3r

翻译自: https://www.pybloggers.com/2016/01/notebook-microservice-and-swagger/

swagger 微服务