swagger生成接口文档-优快云博客

本文链接：https://blog.youkuaiyun.com/m0_61682705/article/details/127185122

一.前言

二.文档(swagger)框架准备

2.1 swagger框架pom依赖

2.2 创建一个config类，用于配置swagger2

2.3rest接口

2.4swagger框架注解

三.看文档显示结果

一.前言

今天就给大家介绍一款接口管理神器swagger2，swagger2的出现就是为了从根本上解决上述问题，它作为一个规范和完整的框架，可以用于生成、描述、调用和可视化 RESTful 风格的 Web 服务：

接口文档在线自动生成
文档随接口变动实时更新，节省维护成本
支持在线接口测试，不依赖第三方工具

二.文档(swagger)框架准备

2.1 swagger框架pom依赖

<!--swagger2-->
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>3.0.0</version>
</dependency>
<dependency>
    <groupId>com.github.xiaoymin</groupId>
    <artifactId>knife4j-spring-boot-starter</artifactId>
    <version>3.0.2</version>
</dependency>

2.2 创建一个config类，用于配置swagger2

@Configuration
@EnableSwagger2//开启swagger2
@EnableKnife4j//启用swagger2的一个ui样式
public class Swagger2Config {
    @Bean
    public Docket createRestApi() {
        return  new Docket(DocumentationType.SWAGGER_2)
                .useDefaultResponseMessages(false)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example"))//扫描哪个包下的接口
                .paths(PathSelectors.any()) // 可以根据url路径设置哪些请求加入文档，忽略哪些请求 Swagger 会扫描该包下所有 Controller 定义的 API，并产生文档内容（除了被 @ApiIgnore 指定的请求）
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("lesson16接口api文档")//标题文字
                .description("接口api文档")//接口描述
                .contact(new Contact("skywalker","http://www.baidu.com","53816565@qq.com"))//联系人相关信息
                .termsOfServiceUrl("http://localhost:8080/")//设置文档的License信息
                .version("1.0")//接口版本号
                .build();
    }
}

2.3rest接口

@Api(tags = "用户相关api")
@Slf4j
@RestController
public class UserController {
    @ApiOperation("根据用户id获取详细")
    @GetMapping("detail")
    public String detail(@RequestParam(value = "userId")@ApiParam("用户id") String userId) {
        //TODO: 实际业务处理
        return "OK";
    }

    @ApiOperation("保存新用户")
    @PostMapping("save")
    public UserDto save( @RequestBody UserDto dto){
        return new UserDto();
    }
}

@ApiModel("用户对象")
@Data
public class UserDto {
    @ApiModelProperty(value = "用户名",required = true)
    private String username;
    @Enumerated(EnumType.STRING)
    @ApiModelProperty("性别")
    private SexEnum sex;
    @ApiModelProperty(value = "密码",required = true)
    private String password;
    @ApiModelProperty("年龄")
    private Integer age;
    @ApiModelProperty("邮箱")
    private String email;
}