AI专业者开发社区 1 号成员
  •  0 回帖  •  3 浏览  •  5 个月前
   

Spring Boot 2.x （十二）：Swagger2的正确玩儿法

Swagger2 简介

简单的来说，Swagger2 的诞生就是为了解决前后端开发人员进行交流的时候API 文档难以维护的痛点，它可以和我们的 Java 程序完美的结合在一起，并且可以与我们的另一开发利器 Spring Boot 来配合使用。

开始使用

第一步：导入 POM 文件

 		<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency> 

	<span class="hljs-comment">&lt;!-- 这里使用 swagger-bootstrap-ui 替代了原有丑陋的ui，拯救处女座~ --&gt;</span>
    <span class="hljs-tag">&lt;<span class="hljs-name">dependency</span>&gt;</span>
        <span class="hljs-tag">&lt;<span class="hljs-name">groupId</span>&gt;</span>com.github.xiaoymin<span class="hljs-tag">&lt;/<span class="hljs-name">groupId</span>&gt;</span>
        <span class="hljs-tag">&lt;<span class="hljs-name">artifactId</span>&gt;</span>swagger-bootstrap-ui<span class="hljs-tag">&lt;/<span class="hljs-name">artifactId</span>&gt;</span>
        <span class="hljs-tag">&lt;<span class="hljs-name">version</span>&gt;</span>1.9.0<span class="hljs-tag">&lt;/<span class="hljs-name">version</span>&gt;</span>
    <span class="hljs-tag">&lt;/<span class="hljs-name">dependency</span>&gt;</span>

第二步：添加配置类

我们需要新增一个 Swagger2Config 的配置类：

/**
 *	Swagger2 配置类
 * @author vi	
 * @since 2019/3/6 8:31 PM
 */
@Configuration
public class Swagger2Config {

<span class="hljs-meta">@Bean</span>
<span class="hljs-keyword">public</span> Docket <span class="hljs-title function_">createRestApi</span><span class="hljs-params">()</span> {
    <span class="hljs-keyword">return</span> <span class="hljs-keyword">new</span> <span class="hljs-title class_">Docket</span>(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            .apis(RequestHandlerSelectors.basePackage(<span class="hljs-string">"indi.viyoung.viboot.*"</span>))
            .paths(PathSelectors.any())
            .build();
}

<span class="hljs-keyword">private</span> ApiInfo <span class="hljs-title function_">apiInfo</span><span class="hljs-params">()</span> {
    <span class="hljs-keyword">return</span> <span class="hljs-keyword">new</span> <span class="hljs-title class_">ApiInfoBuilder</span>()
            .title(<span class="hljs-string">"viboot-swagger2"</span>)	<span class="hljs-comment">//标题</span>
            .description(<span class="hljs-string">"Restful-API-Doc"</span>)	<span class="hljs-comment">//描述</span>
            .termsOfServiceUrl(<span class="hljs-string">"https://www.cnblogs.com/viyoung"</span>) <span class="hljs-comment">//这里配置的是服务网站，我写的是我的博客园站点~欢迎关注~</span>
            .contact(<span class="hljs-keyword">new</span> <span class="hljs-title class_">Contact</span>(<span class="hljs-string">"Vi的技术博客"</span>, <span class="hljs-string">"https://www.cnblogs.com/viyoung"</span>, <span class="hljs-string">"18530069930@163.com"</span>)) <span class="hljs-comment">// 三个参数依次是姓名，个人网站，邮箱</span>
            .version(<span class="hljs-string">"1.0"</span>) <span class="hljs-comment">//版本</span>
            .build();
}



}

第三步：在启动类中添加配置

注意一定要记得添加@EnableSwagger2注解

/**
 * @author vi
 * @since 2019/3/6 6:35 PM
 */
@SpringBootApplication
@ComponentScan(value = "indi.viyoung.viboot.*")
@MapperScan(value = "indi.viyoung.viboot.swagger2.mapper")
@EnableSwagger2
@EnableSwaggerBootstrapUI
public class ViBootSwaggerApplication {
    public static void main(String[] args) {
        SpringApplication.run(ViBootSwaggerApplication.class, args);
    }
}

第四步：通过注解来完成 API 文档

1. @Api
注解名称 注解属性 作用域 属性作用
@Api tags 类 说明该类的作用
value 类 说明该类的作用

举个🌰：

@Api(value = "用户类控制器",tags="用户类控制器")
public class UserController {
...
}

2 . @ApiOperation
注解名称 注解属性 作用域 属性作用
@ApiOperation() value 方法 描述方法作用
notes 方法 提示内容
tags 方法 分组

举个🌰：

 	@ApiOperation(value = "获取用户列表",notes = "获取用户列表")
    public List<User> get() {
     	...   
	}

3. @ApiParam
注解名称 注解属性 作用域 属性作用
@ApiParam() name 方法参数 参数名
value 方法参数 参数说明
required 方法参数 是否必填

举个🌰：

	@ApiOperation(value="获取用户详细信息", notes="根据 url 的 id 来获取用户详细信息")
    public User get(@ApiParam(name="id",value="用户 id",required=true) Long id) {
        log.info("GET..{}... 方法执行。。。",id);
        return userService.getById(id);
    }

4. @ApiModel && @ApiModelProperty
注解名称 注解属性 作用域 属性作用
@ApiModel() value 类 对象名
description 类 描述
@ApiModelProperty() value 方法 字段说明
name 方法 属性名
dataType 方法 属性类型
required 方法 是否必填
example 方法 举例
hidden 方法 隐藏

举个🌰：

@ApiModel(value="user 对象",description="用户对象 user")
public class User implements Serializable {

<span class="hljs-keyword">private</span> <span class="hljs-keyword">static</span> <span class="hljs-keyword">final</span> <span class="hljs-type">long</span> <span class="hljs-variable">serialVersionUID</span> <span class="hljs-operator">=</span> <span class="hljs-number">1L</span>;

<span class="hljs-meta">@TableId(value = "id", type = IdType.AUTO)</span>
<span class="hljs-meta">@ApiModelProperty(value = "用户ID",example = "1000001",hidden=true)</span>
<span class="hljs-keyword">private</span> Long id;

<span class="hljs-meta">@ApiModelProperty(value="用户名",required = true,dataType = "String")</span>
<span class="hljs-keyword">private</span> String userName;

<span class="hljs-meta">@ApiModelProperty(value = "密码")</span>
<span class="hljs-keyword">private</span> String password;



}

5. @ApiImplicitParam && @ApiImplicitParams
`@ApiImplicitParam` 可以单个用于方法至上，多个参数的话可以把 `@ApiImplicitParam` 放到 `@ApiImplicitParams` 中，这里只罗列 `@ApiImplicitParam`的属性：
注解名称 注解属性 作用域 属性作用
@ApiImplicitParam() value 方法 参数说明
name 方法 参数名
dataType 方法 数据类型
paramType 方法 参数类型
example 方法 举例

举个🌰：

	@ApiImplicitParams({@ApiImplicitParam(name = "user", value = "用户实体 user", required = true, dataType = "User")
    })
    public void put(User user) {
        userService.updateById(user);
        log.info("PUT 方法执行。。。");
    }

这里需要注意一点，我们并没有在注解中写图中圈中的两个参数，这个是去读取了我们刚刚为User类的注解，并将用户名设置为必填！

6.@ApiResposne && @ApiResponses

@ApiResponses与@ApiResponse的关系和@ApiImplicitParam && @ApiImplicitParams 的关系和用法都是类似的

注解名称 注解属性 作用域 属性作用
@ApiResponse() response 方法 返回类
code 方法 返回码
message 方法 返回信息
examples 方法 例子

最后再聊聊这个 UI

先贴几张 spring-fox 的 ui（正是我们所熟知的那一套）

相信看到这里，大家心里对于这两套 UI 的选择应该都有个答案了，当然 bootstrap 风格的 ui 不仅好看，而且有各种强大的功能 ~

  1. 导出 md 文档

  2. 参数缓存

公众号

原创文章，文笔有限，才疏学浅，文中若有不正之处，万望告知。