博客
关于我
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一个表A中多个字段关联了表B的ID,如何关联查询?
    查看>>
    MYSQL一直显示正在启动
    查看>>
    MySQL一站到底!华为首发MySQL进阶宝典,基础+优化+源码+架构+实战五飞
    查看>>
    MySQL万字总结!超详细!
    查看>>
    Mysql下载以及安装(新手入门,超详细)
    查看>>
    MySQL不会性能调优?看看这份清华架构师编写的MySQL性能优化手册吧
    查看>>
    MySQL不同字符集及排序规则详解:业务场景下的最佳选
    查看>>
    Mysql不同官方版本对比
    查看>>
    MySQL与Informix数据库中的同义表创建:深入解析与比较
    查看>>
    mysql与mem_细说 MySQL 之 MEM_ROOT
    查看>>
    MySQL与Oracle的数据迁移注意事项,另附转换工具链接
    查看>>
    mysql丢失更新问题
    查看>>
    MySQL两千万数据优化&迁移
    查看>>
    MySql中 delimiter 详解
    查看>>
    MYSQL中 find_in_set() 函数用法详解
    查看>>