博客
关于我
springboot swagger2
阅读量:375 次
发布时间:2019-03-05

本文共 2930 字,大约阅读时间需要 9 分钟。

Spring Boot Swagger2配置与应用指南

初始化Spring Boot项目环境

创建一个新的Spring Boot项目,确保项目依赖中包含必要的组件。重点添加以下依赖:

io.springfox
springfox-swagger2
2.9.2
io.springfox
springfox-swagger-ui
2.9.2
org.springframework.boot
spring-boot-starter-web
2.5.0

Swagger2配置示例

通过以下配置类实现Swagger2的集成:

@Configuration@EnableSwagger2public class SwaggerConfig {    @Bean    public Docket createRestApi() {        return new Docket(DocumentationType.SWAGGER_2)                .pathMapping("/")                .select()                .apis(RequestHandlerSelectors.basePackage("com.example.controller"))                .paths(PathSelectors.any())                .build()                .apiInfo(new ApiInfoBuilder()                        .title("Spring Boot Swagger文档")                        .description("详细的API文档说明")                        .version("1.0.0")                        .contact(new Contact("Swagger团队", "http://example.com", "support@example.com"))                        .license("Apache License 2.0")                        .licenseUrl("http://www.apache.org"));    }}

接口注解使用指南

在实际开发中,注解的使用非常重要:

  • @Api:标记一个Controller类,说明它的功能。
  • @ApiOperation:描述一个方法的作用,提供API的详细说明。
  • @ApiImplicitParams:定义参数,支持默认值和必填属性。
  • @ApiModel:用于实体类注释,描述字段的作用和约束条件。

示例代码:

@RestController@Api(tags = "用户管理接口")@RequestMapping("/user")public class UserController {    @PostMapping("/")    @ApiOperation("添加用户")    @ApiImplicitParams({            @ApiImplicitParam(name = "username", value = "用户名", defaultValue = "李四"),            @ApiImplicitParam(name = "address", value = "地址", defaultValue = "深圳", required = true)    })    public RespBean addUser(@RequestBody User user) {        // 实现用户添加逻辑        return new RespBean("200", "用户添加成功");    }        @GetMapping("/{id}")    @ApiOperation("查询用户信息")    @ApiImplicitParam(name = "id", value = "用户ID", defaultValue = "1", required = true)    public User getUserById(@PathVariable Long id) {        // 实现用户查询逻辑        User user = new User();        user.setId(id);        return user;    }}

安全配置注意事项

在Spring Security中,为了确保Swagger2文档的访问:

@Overrideprotected void configure(WebSecurity web) throws Exception {    web.ignoring()        .antMatchers("/swagger-ui.html")        .antMatchers("/v2/**")        .antMatchers("/swagger-resources/**");}

这样配置后, Swagger页面和文档将不受认证限制,确保开发和测试环境的顺利运行。

常见问题解答

  • 为什么 Swagger文档被403Forbidden了?

    • 检查Security配置,确保Swagger相关路径未被拦截。
    • 可以在安全配置中添加忽略路径,例如:
      web.ignoring()    .antMatchers("/swagger-ui.html")    .antMatchers("/v2/**")    .antMatchers("/swagger-resources/**");
  • 如何处理参数默认值?

    • 使用@ApiImplicitParam注解,指定defaultValue属性即可:
      @ApiImplicitParam(name = "username", value = "李四", defaultValue = "李四")
  • 如何展示请求示例?

    • @ApiOperation中使用example字段:
      @ApiOperation(example = "2020-01-01", requestMethod = "GET")
  • 通过以上配置和示例,可以轻松完成Spring Boot项目的Swagger2集成与文档编写,提升开发效率和API文档的可读性。

    转载地址:http://adwwz.baihongyu.com/

    你可能感兴趣的文章
    Mysql学习总结(56)——MySQL用户管理和权限设置
    查看>>
    Mysql学习总结(57)——MySQL查询当天、本周、本月、上周、本周、上月、距离当前现在6个月数据
    查看>>
    Mysql学习总结(58)——深入理解Mysql的四种隔离级别
    查看>>
    Mysql学习总结(59)——数据库分库分表策略总结
    查看>>
    Mysql学习总结(5)——MySql常用函数大全讲解
    查看>>
    Mysql学习总结(60)——并发量大、数据量大的互联网业务数据库设计规范总结
    查看>>
    Mysql学习总结(61)——MySQL优化之DBA级优化整理汇总
    查看>>
    Mysql学习总结(62)——MySQL连接com.mysql.jdbc.exceptions.jdbc4.CommunicationsException: Communications link问题
    查看>>
    Mysql学习总结(63)——Mysql数据库架构方案选择与分析
    查看>>
    Mysql学习总结(64)——Mysql配置文件my.cnf各项参数解读
    查看>>
    Mysql学习总结(65)——项目实战中常用SQL实践总结
    查看>>
    Mysql学习总结(66)——设置MYSQL数据库编码为UTF-8
    查看>>
    Mysql学习总结(67)——MYSQL慢查询日志
    查看>>
    Mysql学习总结(68)——MYSQL统计每天、每周、每月、每年数据 SQL 总结
    查看>>
    Mysql学习总结(69)——Mysql EXPLAIN 命令使用总结
    查看>>
    Mysql学习总结(6)——MySql之ALTER命令用法详细解读
    查看>>
    Mysql学习总结(70)——MySQL 优化实施方案
    查看>>
    Mysql学习总结(71)——MySQL 重复记录查询与删除总结
    查看>>
    Mysql学习总结(71)——数据库介绍(MySQL安装 体系结构、基本管理)再回顾
    查看>>
    Mysql学习总结(72)——MySQL 开发者开发,设计规范再总结
    查看>>