传统的APIs文档是通过手工编写而成,存在如下弊端
- 文档和代码处于不同的位置,文档需要开发人员来维护,对接口的增删改查需要在文档中进行同步。
- 文档格式不统一。
- 文档共享需要借助外部工具或者自己开发网站。
Swagger特征
- 通过代码和注释自动生成文档。在Swagger框架下,开发人员可对服务进行归类说明,对方法,模型,返回结果等进行详细说明。方便开发人员在编写代码的同时,编写文档信息。自动生成,只需很少的编辑工作,就能获得完整的REST APIs文档
- 提供了UI界面。既展示接口信息,又提供了参数校验,测试功能
- 形成了文档规范,支持不同的语言
- 提供丰富的组件。
- 引入所需要的jar
<!-- Swagger UI 相关 -->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>${swagger.version}</version>
<exclusions>
<exclusion>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
</exclusion>
<exclusion>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
</exclusion>
</exclusions>
</dependency>
<!--画面-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>${swagger.version}</version>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-annotations</artifactId>
<version>1.5.21</version>
</dependency>
<dependency>
<groupId>io.swagger</groupId>
<artifactId>swagger-models</artifactId>
<version>1.5.21</version>
</dependency>
- 创建common模块,并在system模块中引用
<!-- common模块创建方式见上一章 -->
<!-- 在system模块中引用common模块 -->
<dependency>
<groupId>xb.hou</groupId>
<artifactId>demo-common</artifactId>
<version>1.0-SNAPSHOT</version>
</dependency>
- 在common模块中编写swagger配置类
package xb.hou.config;
import com.google.common.base.Predicates;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;
/**
* @title: Swagger配置类
* @Author xbhou
* @Date: 2021-04-16 20:53
* @Version 1.0
*/
@Configuration
@EnableSwagger2
public class SwaggerConfig {
// 控制swagger-ui的开启或关闭
@Value("${swagger.enabled}")
private Boolean enabled;
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.enable(enabled)
.pathMapping("/")
.apiInfo(apiInfo())
.select()
.paths(Predicates.not(PathSelectors.regex("/error.*")))
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.description("一个简单且易上手的 Spring boot 后台管理框架")
.title("学习")
.version("1.0")
.build();
}
}
- 编写controller类进行测试
package xb.hou.user.controller;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiOperation;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
/**
* @title: UserController
* @Author xbhou
* @Date: 2021-04-16 20:40
* @Version 1.0
*/
@RestController
@Api(tags = "用户管理")
@RequestMapping("/user")
public class UserController {
@GetMapping("/get")
@ApiOperation("获取用户信息")
public String getUser() {
return "User";
}
}
- 访问http://localhost:8000/swagger-ui.html,确认是否集成成功
-
swagger的常用API
@Api:用在请求的类上,表示对类的说明 tags="说明该类的作用,可以在UI界面上看到的注解" value="该参数没什么意义,在UI界面上也看到,所以不需要配置" @ApiOperation:用在请求的方法上,说明方法的用途、作用 value="说明方法的用途、作用" notes="方法的备注说明" @ApiImplicitParams:用在请求的方法上,表示一组参数说明 @ApiImplicitParam:用在@ApiImplicitParams注解中,指定一个请求参数的各个方面 name:参数名 value:参数的汉字说明、解释 required:参数是否必须传 paramType:参数放在哪个地方 · header --> 请求参数的获取:@RequestHeader · query --> 请求参数的获取:@RequestParam · path(用于restful接口)--> 请求参数的获取:@PathVariable · body(不常用) · form(不常用) dataType:参数类型,默认String,其它值dataType="Integer" defaultValue:参数的默认值 @ApiResponses:用在请求的方法上,表示一组响应 @ApiResponse:用在@ApiResponses中,一般用于表达一个错误的响应信息 code:数字,例如400 message:信息,例如"请求参数没填好" response:抛出异常的类 @ApiModel:用于响应类上,表示一个返回响应数据的信息 (这种一般用在post创建的时候,使用@RequestBody这样的场景, 请求参数无法使用@ApiImplicitParam注解进行描述的时候) @ApiModelProperty:用在属性上,描述响应类的属性