Spring boot 集成 Swagger

Spring Boot集成Swagger2教程

最新推荐文章于 2024-06-27 11:38:06 发布

原创最新推荐文章于 2024-06-27 11:38:06 发布 · 317 阅读

0 ·

CC 4.0 BY-SA版权

第三方插件集成专栏收录该内容

2 篇文章

订阅专栏

本文详细介绍如何在Spring Boot项目中集成Swagger2实现API文档自动生成。包括Maven依赖配置、Swagger配置类编写、Controller注解使用及响应参数注释等关键步骤。

1，Maven 依赖

<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>

2，配置文件

@Configuration
@EnableSwagger2
public class SwaggerConfig {
    @Bean
    public Docket buildDocket(){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(buildApiInf())
                .select()
                .apis(RequestHandlerSelectors.basePackage("nm.example.swagger.controller"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo buildApiInf(){
        return new ApiInfoBuilder()
                .title("Swagger 集成")
                .description("springboot swagger2")
                .termsOfServiceUrl("http://xgdyc.ml")
                .contact(new Contact("xxx", "http://xgdyxc.ml", "xxx@163.com"))
                .build();

    }
}

3，Controller代码

@Api(value = "UserInfoController", description = "UserInfoController", position = 1)
@Controller
@RequestMapping("/UserInfoController")
public class UserInfoController {

    @ResponseBody
    @RequestMapping(value = "/query", method= RequestMethod.POST)
    @ApiOperation(value = "查询用户", notes = "返回用户实体对象",response = UserReturnDoc.class)
    @ApiImplicitParams(value = {
            @ApiImplicitParam(name = "id",value = "用户id",dataType = "Integer",required = true,example = "1")
    })
    public UserInfo query(@RequestParam(value="id")Long id){
        UserInfo userInfo = new UserInfo();
        userInfo.setId(id);
        userInfo.setName("张三");
        userInfo.setAddress("广州");
        return userInfo;
    }
}

4，业务处理完成后，返回的参数注释，bean 描述

@Getter
@Setter
@ApiModel(value = "用户对象",description = "用户对象",subTypes = {UserReturnDoc.Data.class})
public class UserReturnDoc {
    @ApiModelProperty(value = "业务状态",dataType = "Integer",required = true,notes = "业务状态",example = "业务状态（0、操作成功）")
    private Integer state;
    @ApiModelProperty(value = "业务状态描述",dataType = "String",required = true,notes = "业务状态描述",example = "业务状态描述")
    private String message;

    private Data userInfo;


    @Getter
    @Setter
    @ApiModel(value = "用户信息",description = "用户信息")
    class Data{
        @ApiModelProperty(value = "用户名称",dataType = "String",required = true,notes = "用户名称",example = "用户名称")
        private String userName;
        @ApiModelProperty(value = "用户密码",dataType = "String",required = true,notes = "用户密码",example = "用户密码")
        private String password;
    }
}