版权声明:本文为博主原创文章,遵循 CC 4.0 BY-SA 版权协议,转载请附上原文出处链接和本声明。
Swagger 是一款RESTFUL接口的、基于YAML、JSON语言的文档在线自动生成、代码自动生成的工具。当然也有缺点,最明显的就是代码移入性比较强。
如今为了前后端项目更好的对接,还是为了以后交接方便,都有要求写API接口文档。
1.pom.xml
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.9.2</version>
</dependency>
<!-- 网站依赖http://localhost:8080/swagger-ui.html-->
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.9.2</version>
</dependency>
2.启动类
@SpringBootApplication
@EnableSwagger2//表示开启Swagger
public class SwaggerApplication {
public static void main(String[] args) {
SpringApplication.run(SwaggerApplication.class, args);
}
}
3.Swagger配置类
package org.javaboy.swagger.Config;
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.builders.RequestHandlerSelectors;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
@Configuration //配置类
public class Swagger2Config {
/**
* org.javaboy.swagger.controller包的路径,不然生成的文档扫描不到接口
* @return
*/
@Bean
Docket docket(){
return new Docket(DocumentationType.SWAGGER_2)
.select()
.apis(RequestHandlerSelectors.basePackage("org.javaboy.swagger.controller"))
.paths(PathSelectors.any())
.build()
.apiInfo(new ApiInfoBuilder()
.description("描述:人员信息用户模块...")
.title("标题:某公司_用户信息管理系统_接口文档")
.version("V1.0")
.contact(new Contact("大师兄","[email protected]","[email protected]"))
.build());
}
}
4.编写接口文档
package org.javaboy.swagger.controller;
import io.swagger.annotations.Api;
import io.swagger.annotations.ApiImplicitParam;
import io.swagger.annotations.ApiImplicitParams;
import io.swagger.annotations.ApiOperation;
import org.javaboy.swagger.model.User;
import org.springframework.web.bind.annotation.*;
@RestController
@Api(tags="用户接口") //相当于类注释
public class UserController {
@GetMapping("/hello")
public String hello(){
return "heeo swagger测试";
}
@GetMapping("/user")
@ApiOperation("根据用户id查询") //相当于方法注释
@ApiImplicitParam(name = "查询id",value = "用户id",defaultValue = "99") // 相当方法的参数注释
public User getUserId(Integer id){
User user = new User();
user.setId(id);
return user;
}
@PutMapping("/user")
@ApiOperation("根据id更新用户名")
@ApiImplicitParams({ //这注解能写多个参数注释
@ApiImplicitParam(name = "id",value = "用户id",defaultValue = "99"),
@ApiImplicitParam(name = "username",value="用户名",defaultValue = "默认值")
})
public User updateUsernameById(String username,Integer id){
User user = new User();
user.setId(id);
user.setUsername(username);
return user;
}
@DeleteMapping("/user{id}")
@ApiOperation("根据id删除用户")
@ApiImplicitParam(name = "id",value = "用户id",defaultValue = "99")
public void deleteUserById(@PathVariable Integer id){
System.out.println(id);
}
@PostMapping("/user")
@ApiOperation("根据对象添加用户")
public User addUser(@RequestBody User user){
return user;
}
}
实体类
package org.javaboy.swagger.model;
import io.swagger.annotations.ApiModel;
import io.swagger.annotations.ApiModelProperty;
import java.util.Date;
@ApiModel("用户实体类") //字段比较多就注释
public class User {
@ApiModelProperty("用户id") //注释
private int id;
@ApiModelProperty("用户名")
private String username;
@ApiModelProperty("年龄")
private int age;
@ApiModelProperty("时间")
private Date ctm;
http://localhost:8080/swagger-ui.html
这一遍修改中文文章不错
参考文章
参考文章