博客
关于我
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/

    你可能感兴趣的文章
    Mysql5.7版本单机版my.cnf配置文件
    查看>>
    mysql5.7的安装和Navicat的安装
    查看>>
    mysql5.7示例数据库_Linux MySQL5.7多实例数据库配置
    查看>>
    Mysql8 数据库安装及主从配置 | Spring Cloud 2
    查看>>
    mysql8 配置文件配置group 问题 sql语句group不能使用报错解决 mysql8.X版本的my.cnf配置文件 my.cnf文件 能够使用的my.cnf配置文件
    查看>>
    MySQL8.0.29启动报错Different lower_case_table_names settings for server (‘0‘) and data dictionary (‘1‘)
    查看>>
    MYSQL8.0以上忘记root密码
    查看>>
    Mysql8.0以上重置初始密码的方法
    查看>>
    mysql8.0新特性-自增变量的持久化
    查看>>
    Mysql8.0注意url变更写法
    查看>>
    Mysql8.0的特性
    查看>>
    MySQL8修改密码报错ERROR 1819 (HY000): Your password does not satisfy the current policy requirements
    查看>>
    MySQL8修改密码的方法
    查看>>
    Mysql8在Centos上安装后忘记root密码如何重新设置
    查看>>
    Mysql8在Windows上离线安装时忘记root密码
    查看>>
    MySQL8找不到my.ini配置文件以及报sql_mode=only_full_group_by解决方案
    查看>>
    mysql8的安装与卸载
    查看>>
    MySQL8,体验不一样的安装方式!
    查看>>
    MySQL: Host '127.0.0.1' is not allowed to connect to this MySQL server
    查看>>
    Mysql: 对换(替换)两条记录的同一个字段值
    查看>>