swagger-自动生成接口文档,环境搭建

前后端分离开发,节约时间,编写java代码的同时,自动生成API文档

使用springboot+maven

maven地址

1
2
3
4
5
6
7
8
9
10
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger2</artifactId>
<version>2.4.0</version>
</dependency>
<dependency>
<groupId>io.springfox</groupId>
<artifactId>springfox-swagger-ui</artifactId>
<version>2.4.0</version>
</dependency>

配置文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
@Configuration
@EnableSwagger2
public class SwaggerConfiguration {

@Bean
public Docket createRestApi() {
List<Parameter> pars = new ArrayList<Parameter>();
return new Docket(DocumentationType.SWAGGER_2)
.apiInfo(apiInfo())
.select()
.apis(RequestHandlerSelectors.basePackage("com.example.demo.controller"))
.paths(PathSelectors.any())
.build().globalOperationParameters(pars);
}

private ApiInfo apiInfo() {
return new ApiInfoBuilder()
.title("Swagger-Demo")
.description("接口api")
.version("1.0")
.build();
}
}

配置springboot启动文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
@SpringBootApplication
public class DemoApplication {

public static void main(String[] args) throws UnknownHostException {
SpringApplication.run(DemoApplication.class, args);
InetAddress addr = InetAddress.getLocalHost();
//获取本机ip
String ip = addr.getHostAddress();
//获取本机计算机名称
String hostName = addr.getHostName();
System.out.println("服务器IP " + ip);
System.out.println("服务器名称 " + hostName);
System.err.println("swagger:http://" + ip + ":8080/swagger-ui.html");
}

}

启动项目

访问控制台的地址即可:http://192.168.88.8:8080/swagger-ui.html

环境搭建完毕,写个例子,更多的参数百度即可

举个栗子

有两种写法

  • 第一种:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    @Api(tags = {"用户相关操作API:"})
    @RestController
    @RequestMapping("/user")
    public class UserController {

    @ApiOperation("用户注册")
    @ApiImplicitParams(value = {
    @ApiImplicitParam(name = "phone", value = "手机号",
    required = true, paramType = "query", dataType = "string"),
    @ApiImplicitParam(name = "password", value = "密码",
    required = true, paramType = "query", dataType = "string"),
    @ApiImplicitParam(name = "code", value = "验证码",
    required = true, paramType = "query", dataType = "string")
    })
    @PostMapping("/register")
    public void register(String code, String phone, String password) {
    System.out.println("hello");
    }

    }
  • 第二种:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    @Api(tags = {"用户相关操作API:"})
    @RestController
    @RequestMapping("/user")
    public class UserController {

    @ApiOperation("用户注册")
    @PostMapping("/register")
    public void register(@ApiParam(value = "验证码", required = true) String code,
    @ApiParam(value = "手机号", required = true) String phone,
    @ApiParam(value = "密码") String password) {
    System.out.println("hello");
    }

    }

效果如下

  • 有一点要注意,最好指定请求方式,post或者get,如果使用@RequestMapping,就会出现如下情况

一个方法还好,如果很多个方法,就很乱了

Controller写的注解,会自动生成,很方便

填写对应的参数,点击Try it out! 即可发起请求

一般使用这几个注解足够了,如果想把文档写好点,可以用其他的几个注解完善完善~


还有一点,关于@ModelAttribute注解,如果用实体类接收参数

  • 写了@ApiParam就不要写@ModelAttribute
  • 反之,写了@ModelAttribute就不要写@ApiParam
  • 只能存在1个,不然会重复出现

举个栗子:

1
2
3
4
5
6
7
8
    @ApiOperation("用户注册")
@RequestMapping("/register")
public void register(@ApiParam(value = "验证码", required = true) String code,
@ApiParam(value = "手机号", required = true) String phone,
@ApiParam(value = "密码") String password,
@ModelAttribute User user) {
System.out.println("hello");
}

正确方式

1
2
3
4
5
@ApiOperation("用户注册")
@PostMapping("/register")
public void register(@ModelAttribute User user) {
System.out.println("hello");
}

然后你可能会发现,有的成员有Description,有的没有
是因为如果用@ModelAttribute,默认都没有描述,需要在实体类上加注解

结束~

附上git地址:
swagger-ui-start

------本文结束感谢阅读------

本文标题:swagger-自动生成接口文档,环境搭建

文章作者:churuo

原始链接:https://www.xuchuruo.cn/swagger-自动生成接口文档.html

许可协议: 署名-非商业性使用-禁止演绎 4.0 国际 转载请保留原文链接及作者。

0%