Swaggerhub三件套:Editor、Codegen、UI

福海鑫森

已于 2022-06-07 14:34:14 修改

阅读量3.4k

点赞数

分类专栏：微服务文章标签： swagger

于 2022-06-06 21:58:21 首次发布

原文链接：https://blog.csdn.net/macwinwin/article/details/108682393

版权

微服务专栏收录该内容

4 篇文章 1 订阅

订阅专栏

一般我们在对接前后端的时候，都需要提供相应的接口文档。对于后端来说，编写接口文档即费时费力，还会经常因为没有及时更新，导致前端对接时出现实际接口与文档不一致。而且手写接口文档还容易出错，而swagger很好的解决了这个痛点。

Swagger可用于：1.接口的文档在线自动生成、2.功能测试。

Swagger 是一个规范且完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务。

Swagger 的目标是对 REST API 定义一个标准且和语言无关的接口，可以让人和计算机拥有无须访问源码、文档或网络流量监测就可以发现和理解服务的能力。当通过 Swagger 进行正确定义，用户可以理解远程服务并使用最少实现逻辑与远程服务进行交互。与为底层编程所实现的接口类似，Swagger 消除了调用服务时可能会有的猜测。

Swagger 的优势

支持 API 自动生成同步的在线文档：使用 Swagger 后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
提供 Web 页面在线测试 API：光有文档还不够，Swagger 生成的文档还支持在线测试。参数和格式都定好了，直接在界面上输入参数对应的值即可在线测试接口。

集成 Swagger 管理 API 文档

1）项目中集成 Swagger

集成 Swagger 我们使用封装好了的 Starter 包，代码如下所示。

<!-- Swagger -->
<dependency>
    <groupId>com.spring4all</groupId>
    <artifactId>swagger-spring-boot-starter</artifactId>
    <version>1.7.1.RELEASE</version>
</dependency>

在启动类中使用 @EnableSwagger2Doc 开启 Swagger，代码如下所示。

@EnableSwagger2Doc
@SpringBootApplication
public class AuthApplication {
    public static void main(String[] args) {
        SpringApplication.run(AuthApplication.class, args);
    }
}

2）使用 Swagger 生成文档

Swagger 是通过注解的方式来生成对应的 API，在接口上我们需要加上各种注解来描述这个接口，关于 Swagger 注解的使用在教程后面会有详细讲解，本节只是带大家快速使用 Swagger，使用方法代码如下所示。

@ApiOperation(value = "新增用户")
@ApiResponses({ @ApiResponse(code = 200, message = "OK", response = UserDto.class) })
@PostMapping("/user")
public UserDto addUser(@RequestBody AddUserParam param) {
    System.err.println(param.getName());
    return new UserDto();
}

参数类定义代码如下所示。

@Data
@ApiModel(value = "com.biancheng.auth.param.AddUserParam", description = "新增用户参数")
public class AddUserParam {

    @ApiModelProperty(value = "ID")
    private String id;

    @ApiModelProperty(value = "名称")
    private String name;

    @ApiModelProperty(value = "年龄")
    private int age;
}

在线测试接口

接口查看地址可以通过服务地址 /swagger-ui.html 来访问，见图 1。

可以展开看详情，见图 2。

在 param 中输入参数，点击 Try it out 按钮可以调用接口，见图 3。

说到Swagger就不得不说OpenAPI Specification（OAS），这两个之间存在千丝万缕的联系，不过也不必在意这些细节（主要是我也搞不清），就需要明白

OAS是一个规范；
Swagger是遵从这个规范的一个工具集之一；
OAS目前版本为3.0.3；
OAS规范是用来将RESTFul风格的API更容易被计算机和人类理解的，从这个意义上来说和高级编程语言很像；
常用的Swagger组件包括：


Swagger Editor	开源	本地、SaaS	基于浏览器的API文档编辑器
Swagger Codegen	开源	本地、SaaS	生成服务端、客户端代码
Swagger UI	开源	本地、SaaS	交互式API文档渲染器
SwaggerHub	收费	SaaS	集成上述三个工具的功能官网地址 Build, Collaborate & Integrate APIs \| SwaggerHub

Editor中包含有Codegen功能
Editor、Codegen、UI都提供Docker容器化方式部署部署

Swagger Editor安装

docker pull swaggerapi/swagger-editor
docker run -d -p 10001:8080 swaggerapi/swagger-editor

参考：

GitHub - swagger-api/swagger-editor: Swagger Editor

Swagger Codegen安装(区分OpenAPI 2.0 3.0)

参考：https://github.com/swagger-api/swagger-codegen

参考：https://github.com/swagger-api/swagger-codegen#development-in-docker

官方提供得镜像：Docker Hub

Public Pre-built Docker images

Docker Hub (official web service)
Docker Hub (official CLI)

官方提供OpenAPI 2.0得方法

Supported tags

latest

For more information about this image and the functionality it provides, please see the swagger-codegen GitHub repository.

Usage

Expose port 8080 from the image and load the swagger-ui on the exposed port. You can then access the web service directly from the swagger-ui or via API.

Example

docker pull swaggerapi/swagger-generator

# be sure to set the GENERATOR_HOST based on the IP address of your server!
docker run -d -e GENERATOR_HOST=http://192.168.99.100 -p 80:8080 swaggerapi/swagger-generator

You can now open swagger-ui on your machine via 80:

open http://192.168.99.100

网络上看到OpenAPI3.0得方法试过没有成功

OpenAPI 3.0 (运行失败)
>>> docker pull swaggerapi/swagger-generator
>>> docker run -e "JAVA_MEM=1024m" -e "HTTP_PORT=80" -p 80:80 --name swagger-generator-v3 -v /tmp:/jetty_home/lib/shared swaggerapi/swagger-generator-v3

CLI官方镜像安装

docker pull swaggerapi/swagger-codegen-cli-v3
docker run --rm -v ${PWD}/Downloads:/Downloads swaggerapi/swagger-codegen-cli-v3 generate \
-i /Downloads/openapi.json \
-l python \
-o /Downloads/python

Swagger UI安装

docker pull swaggerapi/swagger-ui
docker run -p 80:8080 -e SWAGGER_JSON=/foo/microfat-test-1.0.0-resolved.json -v ~/Downloads:/foo swaggerapi/swagger-ui

参考文档：https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/installation.md