在这之前,公司的api文档都是自己编写管理的,有些麻烦。所以最近经理就叫我看看这个Swagger,作为一个小白,就参考了别人的写了个Demo,这里稍微记录下。
一、 准备Spring Boot的项目
方式有很多,eclipse中可以使用插件 sts ,或者也可以直接访问
https://start.spring.io/
,下载下来的是个压缩包,解压后导入开发工具即可。
二、引入依赖
这里用的是2.6.1的版本,Spring Boot用的是2.1.7版本
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.6.1</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.6.1</version>
</dependency>
三、编写配置类
@Configuration
public class SwaggerConfig {
@Bean
public Docket createRestApi() {
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.withClassAnnotation(Api.class)) //①
// .apis(RequestHandlerSelectors.basePackage("com.example.demo.controller")) //②
.paths(PathSelectors.any())
.build();
}
private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("swagger2构建api文档")
.description("使用swagger2简单构建生成api文档的demo")
.version("1.0")
.build();
}
}
①这是扫描带有Api注解的类
②这句就是根据指定的包路径来扫描
四、编写Controller接口
@Api(tags="UserController",description="用户管理接口")
@RequestMapping(value="/user")
@Controller
@ResponseBody
public class UserController {
@ApiOperation(value="单条查询", notes="根据id查询用户信息")
@ApiImplicitParam(name="id",value="用户id",dataType="Integer",paramType="path",required=true)
@GetMapping(value="/getUser/{id}")
public User getUserById(@PathVariable(value="id")Integer id) {
User u = new User();
u.setId(id);
u.setName("想是是");
return u;
}
@ApiOperation(value="查询所有")
@GetMapping(value="/findUsers")
public List<User> findUsers(){
User u = new User(1,"小黑");
User u2 = new User(2,"兰兰");
List<User> users = new ArrayList<>();
users.add(u2);
users.add(u2);
return users;
}
}
这里就简单写点好了,我的目的是能生成接口文档就好~~
实体User.class
public class User {
private Integer id;
private String name;
// Getter Setter
}
以上完成后就可以启动项目,然后访问 http://localhost:8080/swagger-ui.html
(该地址就是你项目的 ip:端口/(可能有项目名)/swagger-ui.html)
更多可参考:spring-boot-swagger2 使用手册
相关注解说明:
- @Api:修饰整个类,描述Controller的作用
- @ApiOperation:描述一个类的一个方法,或者说一个接口
- @ApiParam:单个参数描述
- @ApiModel:用对象来接收参数
- @ApiProperty:用对象接收参数时,描述对象的一个字段
- @ApiResponse:HTTP响应其中1个描述
- @ApiResponses:HTTP响应整体描述
- @ApiIgnore:使用该注解忽略这个API
- @ApiError :发生错误返回的信息
- @ApiImplicitParam:一个请求参数
- @ApiImplicitParams:多个请求参数
以上,就完成了!!
可能遇到的问题
可能在整合其他项目时会有页面找不到 404 错误的问题,那就是该静态页面被拦截了,需要放开。
(继承 WebMvcConfigurationSupport)
@Override
protected void addResourceHandlers(ResourceHandlerRegistry registry) {
// 解决静态资源无法访问
registry.addResourceHandler("/**")
.addResourceLocations("classpath:/static/");
// 解决swagger无法访问
registry.addResourceHandler("/swagger-ui.html")
.addResourceLocations("classpath:/META-INF/resources/");
// 解决swagger的js文件无法访问
registry.addResourceHandler("/webjars/**")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
}
好了,写的有点久了,该溜了~~~~(以上内容均来自参考)