Swagger2快速使用手册（SpringBoot 2.6环境）

目录

① 配置下载两个依赖

② 声明swagger配置类

③ 配置静态资源映射

④ 访问Swagger API管理页面

常用注解，描述API

控制器相关常用注解

 实体类常用注解

---

① 配置下载两个依赖

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>

② 声明swagger配置类

目的：配置Swagger包扫描 和 API管理页面等相关信息。

注意：

• 在配置类上添加@EnableSwagger2注解以启用Swagger。
• 在配置中设置好自己的接口包扫描路径。

@Configuration
@EnableSwagger2
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                //是否启用swagger接口信息 (true 开启  false隐藏。生产环境建议隐藏)
//                .enable(false)
                .select()
                //扫描包路径，捕获注解声明的接口
                .apis(RequestHandlerSelectors.basePackage("com.mh"))
                .paths(PathSelectors.any())
                .build();
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                //设置文档标题
                .title("我是接口文档标题")
                //设置文档描述
                .description("我是接口文档说明")
                //服务条款URL连接
                .termsOfServiceUrl("http://localhost:9089/")
                //声明版本
                .version("1.0.0")
                .build();
    }
}

③ 配置静态资源映射

目的：确保能通过 IP:端口号/swagger-ui.html 访问到管理页面

@Configuration
public class WebMvcConfigurer extends WebMvcConfigurationSupport {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations(
                "classpath:/static/");
        registry.addResourceHandler("swagger-ui.html", "doc.html").addResourceLocations(
                "classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations(
                "classpath:/META-INF/resources/webjars/");
        super.addResourceHandlers(registry);
    }

}

④ 访问Swagger API管理页面

访问地址：ip:端口号/swagger-ui.html  （根据自己实际情况访问）

常用注解，描述API

控制器相关常用注解

例如一个用户接口控制器中的声明：

@RestController
@RequestMapping("/user")
@Api(value = "用户控制器",tags = "用户相关接口", description = "这是用户相关的接口，关于用户相关功能请看这里！")
public class UserController {

    /**
     * 根据id获取用户信息
     * @param id `
     * @return `
     */
    @GetMapping
    @ApiOperation(value = "新增用户", notes = "传入用户的ID,返回用户的信息")
    @ApiImplicitParam(name = "id", value = "用户ID", required = true)
    public User getById(String id){
        return new User();
    }
}

 效果===> 

说明：

@Api中的value属性用于描述控制器类。

@ApiOperation中value属性用于描述方法。

其他属性看效果图对比一下就知道。

 

 实体类常用注解

@ApiModel("用户信息")
public class User {
    @ApiModelProperty("姓名")
    public String name;

    @ApiModelProperty("年龄")
    public Integer age;
}

 效果===> 

注意，在实体类上声明之后到管理页面Models块中查看。