Spring Boot Swagger2生成接口文档

版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。

本文链接： https://blog.csdn.net/weixin_44716935/article/details/102755988

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

这一遍修改中文文章不错
参考文章
参考文章