jumpserver安装及运用

前言:编写和维护接口文档是各种程序员的任务,依照Swagger2可以火速救助大家编辑最新的API接口文档,再也不用担心开会前仍忙于整理各类材料了,直接进步了团伙开发的联络效用。其它,本学科还附加提供了UI汉化教程,去除阅读官方英文界面的烦乱。(目前Swagger汉化教程是找不到的,因为官方手册实在写得太烂。。)

安装

下载
现已首要看git的支行或者tag,不要用默许的dev分支,tag
0.3.2也有难题,推荐用master分支

支行切换
git checkout branch_name
翻开所有tag及注释
git tag -l -n

官网项目文档

适用于版本:v0.3.1-2

SpringBoot + Swagger2 UI界面-汉化教程

源码下载

安装git
yum -y install git

克隆jumpserver

cd /opt
git clone https://github.com/jumpserver/jumpserver.git

注:不要设置在/root、/home 等目录下,避防权限难题

1.默许的英文界面UI

唯恐很多青年人伴都曾经采取过Swagger,但是打开UI界面之后,却是下边那样的画风,纯英文的界面并不太友好,作为国人仍然习惯汉语界面。

图片 1

号称世界最流行的API工具总不应当不支持国际化属性吧,楼主在合法使用手册找到有关本地化和翻译的表明:

图片 2

也就是说,只要加上翻译器和对此的译文JS就足以体现中文界面了。(使用IDEA
双击Shift 飞速找到swagger-ui.html 入口文件)

图片 3

注:对静态资源的存放路径有可疑的请戳:SpringBoot项目组织表明

安装

实践安装脚本

cd jumpserver/install
python install.py

注意:

  1. 设置进度中需求输入数据库密码时,直接回车就行
  2. 形成安装后,请访问web,继续翻看后续文档
  3. 只要开行败北,请回来上层目录,手动运行./service.sh restart启动
  4. 默许账号密码 admin 5Lov@wife
    实际细节:安装图解
    注意:
  5. SMTP的账号输入要带域名后缀,比如:xxx@163.com
  6. 全方位系统中不用出现汉语、特殊字符

2.定制普通话界面

自定义已有的数据库

create user ‘username’@’x.x.x.x’ identified by ‘password’;
create database jumpserver character set utf8;
grant all on jumpserver.* to username@’x.x.x.x’;

安装达成后,输入的配备音信保存在jumpserver.conf中
查阅日志:tail -f /opt/jumpserver/logs/jumpserver.log
注:里面包括了详细的日志,包罗了账号和密码,一切成就后,请将
jumpserver.conf中的log改为 warning等

2.1 添加首页和译文

重大来了,在resourece目录下开创\META-INF\resourece目录,然后创设一个名称为”swagger-ui.html”
的HTML文件。

图片 4

只顾文件名不要起错,接下去将下边那段内容维持原状的正片进去。

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <title>Swagger UI</title>
    <link rel="icon" type="image/png" href="webjars/springfox-swagger-uivicon-32x32.png" sizes="32x32"/>
    <link rel="icon" type="image/png" href="webjars/springfox-swagger-uivicon-16x16.png" sizes="16x16"/>
    <link href='webjars/springfox-swagger-ui/css/typography.css' media='screen' rel='stylesheet' type='text/css'/>
    <link href='webjars/springfox-swagger-ui/css/reset.css' media='screen' rel='stylesheet' type='text/css'/>
    <link href='webjars/springfox-swagger-ui/css/screen.css' media='screen' rel='stylesheet' type='text/css'/>
    <link href='webjars/springfox-swagger-ui/css/reset.css' media='print' rel='stylesheet' type='text/css'/>
    <link href='webjars/springfox-swagger-ui/css/print.css' media='print' rel='stylesheet' type='text/css'/>

    <script src='webjars/springfox-swagger-ui/lib/object-assign-pollyfill.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lib/jquery-1.8.0.min.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lib/jquery.slideto.min.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lib/jquery.wiggle.min.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lib/jquery.ba-bbq.min.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lib/handlebars-4.0.5.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lib/lodash.min.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lib/backbone-min.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/swagger-ui.min.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lib/highlight.9.1.0.pack.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lib/highlight.9.1.0.pack_extended.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lib/jsoneditor.min.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lib/marked.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lib/swagger-oauth.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/springfox.js' type='text/javascript'></script>

    <!--国际化操作:选择中文版 -->
    <script src='webjars/springfox-swagger-ui/lang/translator.js' type='text/javascript'></script>
    <script src='webjars/springfox-swagger-ui/lang/zh-cn.js' type='text/javascript'></script>

</head>

<body class="swagger-section">
<div id='header'>
    <div class="swagger-ui-wrap">
        <a id="logo" href="http://swagger.io">![](webjars/springfox-swagger-uilogo_small.png)swagger</a>
        <form id='api_selector'>
            <div class='input'>
                <select id="select_baseUrl" name="select_baseUrl"></select>
            </div>
            <div class='input'><input placeholder="http://example.com/api" id="input_baseUrl" name="baseUrl" type="text"/></div>
            <div id='auth_container'></div>
            <div class='input'><a id="explore" class="header__btn" href="#" data-sw-translate>Explore</a></div>
        </form>
    </div>
</div>

<div id="message-bar" class="swagger-ui-wrap" data-sw-translate> </div>
<div id="swagger-ui-container" class="swagger-ui-wrap"></div>
</body>
</html>

OK 水到渠成 大家访问
http://localhost:8080/swagger-ui.html
看看显示效果:

图片 5

图片 6

注:关于国际化,直接在Github下载好Swagger-UI的源码,将swagger-ui.html替换成上文,直接发表到Maven私服仓库,使用效率更佳。

WEB使用

2.2 更详尽的译文翻译(非必需)

万一想进一步调动译文,可以在META-INF\resources\webjars\springfox-swagger-ui\lang
目录下添加zh-cn.js文件.

图片 7

接下来在译文(zh-cn.js )依照个体爱好来添加翻译内容,如下

'use strict';

/* jshint quotmark: double */
window.SwaggerTranslator.learn({
    "Warning: Deprecated":"警告:已过时",
    "Implementation Notes":"实现备注",
    "Response Class":"响应类",
    "Status":"状态",
    "Parameters":"参数",
    "Parameter":"参数",
    "Value":"值",
    "Description":"描述",
    "Parameter Type":"参数类型",
    "Data Type":"数据类型",
    "Response Messages":"响应消息",
    "HTTP Status Code":"HTTP状态码",
    "Reason":"原因",
    "Response Model":"响应模型",
    "Request URL":"请求URL",
    "Response Body":"响应体",
    "Response Code":"响应码",
    "Response Headers":"响应头",
    "Hide Response":"隐藏响应",
    "Headers":"头",
    "Try it out!":"试一下!",
    "Show/Hide":"显示/隐藏",
    "List Operations":"显示操作",
    "Expand Operations":"展开操作",
    "Raw":"原始",
    "can't parse JSON.  Raw result":"无法解析JSON. 原始结果",
    "Example Value":"示例",
    "Click to set as parameter value":"点击设置参数",
    "Model Schema":"模型架构",
    "Model":"模型",
    "apply":"应用",
    "Username":"用户名",
    "Password":"密码",
    "Terms of service":"服务条款",
    "Created by":"创建者",
    "See more at":"查看更多:",
    "Contact the developer":"联系开发者",
    "api version":"api版本",
    "Response Content Type":"响应Content Type",
    "Parameter content type:":"参数类型:",
    "fetching resource":"正在获取资源",
    "fetching resource list":"正在获取资源列表",
    "Explore":"浏览",
    "Show Swagger Petstore Example Apis":"显示 Swagger Petstore 示例 Apis",
    "Can't read from server.  It may not have the appropriate access-control-origin settings.":"无法从服务器读取。可能没有正确设置access-control-origin。",
    "Please specify the protocol for":"请指定协议:",
    "Can't read swagger JSON from":"无法读取swagger JSON于",
    "Finished Loading Resource Information. Rendering Swagger UI":"已加载资源信息。正在渲染Swagger UI",
    "Unable to read api":"无法读取api",
    "from path":"从路径",
    "server returned":"服务器返回"
});

===========接下来,正式进入Swagger2的行使教程===========

用户管理

适用于版本:v0.3.0-2
I. 使用Jumpserver前要通晓精通那三个用户关系:

用户:是指你在web上创建的用户,会在跳板机上创设那几个用户,功能就是用来登录跳板机

管制用户:是指客户端上的如root等高权限账号(或普通用户拥有NOPASSWD: ALL
sudo权限), 效用用于推送系统用户

系统用户:是指要在客户端上创建那么些序列用户,通过推送来贯彻,功能就是登录客户端

II. 管理用户和系统用户的涉嫌:

双方都是客户端上的用户,后者提到到一个推送动作,

譬如推送test系统用户,也就是在客户端上创造test用户,那么创造用户需求有权力,
有没有权力成立就要看您是用客户端的root用户如故普通用户做为管理用户,
假定后者做为管理用户就需求添加sudo权限又是NOPASSWD: ALL,
这么推送系统用户,就可以成功在客户端上成立test用户

SpringBoot + Swagger2 使用教程

资本管理

资产组:同用户组,那里是费用重组的汇聚,为了有利于授权.
用度:资产平时是我们的服务器、网络设施、其余ssh协议硬件设施等.

丰富基金时索要丰富一个管理用户,该管理用户是客户端上存有sudo权限的用户,
如root,或者有 NOPASSWD: ALL的用户.
该管理用户用来向资产推送系统用户,假设有关联sudo别名会为系统用户添加sudo.
经过管住用户来取得资金的一对硬件音信.
机房:记录IDC机房音讯

1. 引入看重

    <!--依赖管理 -->
    <dependencies>
        <dependency> <!--添加Web依赖 -->
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency><!--添加Swagger依赖 -->
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.7.0</version>
        </dependency>
        <dependency><!--添加Swagger-UI依赖 -->
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.7.0</version>
        </dependency>
        <dependency> <!--添加热部署依赖 -->
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-devtools</artifactId>
        </dependency>
        <dependency><!--添加Test依赖 -->
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

授权管理

sudo别名、系统用户、授权规则使用
sudo别名:sudo命令列表,八个用逗号隔开,不可能换行
系统用户:客户端的ssh连接账号(系统账号),关联sudo别名,被应用前记得推送到客户端
推送:推送系统用户: 添加完系统用户,必要推送,推送操作是选用ansible.
推送系统用户流程图如下:

Paste_Image.png

授权规则:web用户,资产主机,系统用户三者关系(绑定),控制web普通用户能管理的开销和ssh连接用的连串账号

2. 加上配置

@Configuration //标记配置类
@EnableSwagger2 //开启在线接口文档
public class Swagger2Config {
    /**
     * 添加摘要信息(Docket)
     */
    @Bean
    public Docket controllerApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(new ApiInfoBuilder()
                        .title("标题:某公司_用户信息管理系统_接口文档")
                        .description("描述:用于管理集团旗下公司的人员信息,具体包括XXX,XXX模块...")
                        .contact(new Contact("一只袜子", null, null))
                        .version("版本号:1.0")
                        .build())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.hehe.controller"))
                .paths(PathSelectors.any())
                .build();
    }
}

上次下载

文本上传:
上传文件名能有汉语,能够而且上次两个公文到指定的主机,留存是先上传到管理主机的tmp/{datatime}/文件名,再扩散指定主机的tmp/{datatime}/文件名目录
文件下载:只好下载客户端或服务端主机的/tmp目录中的文件

3. 编制接口文档

日志审计

在线、登陆记录、命令记录、上传下载多种音信

Swagger2 基本采纳:

  • @Api 描述类/接口的主要用途
  • @ApiOperation 描述方法用途
  • @ApiImplicitParam 描述方法的参数
  • @ApiImplicitParams 描述方法的参数(Multi-Params)
  • @ApiIgnore 忽略某类/方法/参数的文档

设置

安顿连接客户端的高等级管理权限账号(可以密码及密钥)

Swagger2 使用表明来编排文档:

Swagger2编写接口文档极度简单,只需求在控制层(Controller)添加评释来叙述接口音信即可。例如:

package com.hehe.controller;

@Api("用户信息管理")
@RestController
@RequestMapping("/user/*")
public class UserController {

    private final static List<User> userList = new ArrayList<>();

    {
        userList.add(new User("1", "admin", "123456"));
        userList.add(new User("2", "jacks", "111111"));
    }

    @ApiOperation("获取列表")
    @GetMapping("list")
    public List userList() {
        return userList;
    }

    @ApiOperation("新增用户")
    @PostMapping("save")
    public boolean save(User user) {
        return userList.add(user);
    }

    @ApiOperation("更新用户")
    @ApiImplicitParam(name = "user", value = "单个用户信息", dataType = "User")
    @PutMapping("update")
    public boolean update(User user) {
        return userList.remove(user) && userList.add(user);
    }

    @ApiOperation("批量删除")
    @ApiImplicitParam(name = "users", value = "N个用户信息", dataType = "List<User>")
    @DeleteMapping("delete")
    public boolean delete(@RequestBody List<User> users) {
        return userList.removeAll(users);
    }
}

package com.hehe.entity;

public class User {

    private String userId;
    private String username;
    private String password;

    public User() {

    }

    public User(String userId, String username, String password) {
        this.userId = userId;
        this.username = username;
        this.password = password;
    }

    @Override
    public boolean equals(Object o) {
        if (this == o) {
            return true;
        }
        if (o == null || getClass() != o.getClass()) {
            return false;
        }

        User user = (User) o;

        return userId != null ? userId.equals(user.userId) : user.userId == null;
    }

    @Override
    public int hashCode() {
        int result = userId != null ? userId.hashCode() : 0;
        result = 31 * result + (username != null ? username.hashCode() : 0);
        result = 31 * result + (password != null ? password.hashCode() : 0);
        return result;
    }

    public String getUserId() {
        return userId;
    }

    public void setUserId(String userId) {
        this.userId = userId;
    }

    public String getUsername() {
        return username;
    }

    public void setUsername(String username) {
        this.username = username;
    }

    public String getPassword() {
        return password;
    }

    public void setPassword(String password) {
        this.password = password;
    }
}

4. 查看接口文档

编辑文档落成之后,启动当前项目,在浏览器打开:
[
http://localhost:8080/swagger-ui.html
] , 看到效果如下:

图片 8

来探视save 方法的切实可行描述,可以观看Swagger 2.7.0
版本对参数列表举办了改版,间接输入参数,更有益于开展测试操作:

图片 9

5. 测试接口

Swagger2的强有力之处不仅在于连忙生成整洁优雅的RestAPI文档,同时支持接口方法的测试操作(类似于客户端PostMan)。

以询问用户列表为例,无参数输入,直接点击“试一下”按钮:

图片 10

然后可以看出以JSON格式重回的用户列表音信,很便宜有木有:

图片 11

好了,关于Swagger2在品种中的使用教程就到此处。

源码下载: SpringBoot +Swagger2
使用教程

专题阅读:《SpringBoot
布道种类》