swagger 自动生成API文档

最新推荐文章于 2025-05-27 00:15:11 发布

程序员路同学

最新推荐文章于 2025-05-27 00:15:11 发布

阅读量305

点赞数

CC 4.0 BY-SA版权

分类专栏： spring 文章标签： spring boot

鹿少年

本文链接：https://blog.youkuaiyun.com/huanglu0314/article/details/117806593

spring 专栏收录该内容

17 篇文章

订阅专栏

本文介绍如何在SpringBoot项目中集成并使用Swagger，包括依赖引入、配置文档生成、静态资源访问及常用注解详解。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

springboot项目中使用swagger

1:引入依赖

 <swagger.version>2.7.0</swagger.version>

  <!--swagger  -->
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger2</artifactId>
                <version>${swagger.version}</version>
            </dependency>
            <dependency>
                <groupId>io.springfox</groupId>
                <artifactId>springfox-swagger-ui</artifactId>
                <version>${swagger.version}</version>
            </dependency>

2:配置swagger

@Configuration
@EnableSwagger2
public class Swagger2Configuration  {

    /**
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     *
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
//                .host("localhost:8080")
                .apiInfo(apiInfo())
                .select()
                // 包下的类，才生成接口文档
                .apis(RequestHandlerSelectors.basePackage("com.manager.controller"))
                .paths(PathSelectors.any()) // 可以根据url路径设置哪些请求加入文档，忽略哪些请求
                .build();
    }

    /**
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/swagger-ui.html
     *
     * @return
     */
    private ApiInfo apiInfo() {

        return new ApiInfoBuilder()
                .title("决策") //设置文档的标题
                .description("API 接口文档") // 设置文档的描述
                .termsOfServiceUrl("http://www.baidu.com/")
                .version("1.0.0") // 设置文档的版本信息-> 1.0.0 Version information
                .build();
    }


}

3:配置静态文件位置

@Configuration
public class CorsConfig implements WebMvcConfigurer {
    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");
        registry.addResourceHandler("swagger-ui.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/**").addResourceLocations("classpath:/META-INF/resources/webjars/");

    }
}

或者在配置文件里指定：

spring 
  resources:
    static-locations: classpath:/static/,classpath:/META-INF/resources/,classpath:/META-INF/resources/webjars/

之所以配置是因为我么可以查看swagger文档html文件位置：

配置完成后只需要在浏览器输入栏输入地址：http://localhost:8082/swagger-ui.html（8082是服务启动的port）

4:讲解swagger常用注解

作用在controller层的注解：

@Api(tags = "业务数据API接口文档")
Api 用在类上，说明该类的作用。可以标记一个Controller类做为swagger 文档资源。
常用属性大致：
  value:url的路径值
  tag:标签，如果设置这个值，value的值会被覆盖
  description: 对APi资源进行描述
  basepath:基本路径可以不配置
  produces: 如application/json,application/xml 主要配置请求的样式
  consumes 和produces一样
  hidden:配置为true 将在文档中隐藏

@ApiOperation(value = "统计业务领域主体", notes = "统计主体下拉列表")
ApiOperation 用在方法上，说明方法的作用

@ApiImplicitParam(name = "params", value = "map参数", dataType = "{ ?page=1&limit=1}", paramType = "query")
ApiImplicitParam用来描述请求参数的信息

@ApiImplicitParams 可以包含多个ApiImplicitParam



ApiParam请求属性,使用方式：
public ResponseEntity<User> createUser(@RequestBody @ApiParam(value = "Created user object", required = true)  User user)


ApiResponse：响应配置，使用方式： 
@ApiResponse(code = 400, message = "Invalid user supplied") 


ApiResponses：响应集配置，使用方式： 
@ApiResponses({ @ApiResponse(code = 400, message = "Invalid Order") })

用在实体类上的注解：

@ApiModel()用于类 ；表示对类进行说明，用于参数用实体类接收 
@ApiModel(value = "业务主体实体类")
属性：
    value–表示对象名 
    description–描述 

@ApiModelProperty()用于方法 表示对model属性的说明或者数据操作更改 
@ApiModelProperty(value = "业务主体编码")

    value–字段说明 
    name–重写属性名字 
    dataType–重写属性类型 
    required–是否必填 
    example–举例说明 
    hidden–隐藏

@ApiIgnore()用于类或者方法上，可以不被swagger显示在页面上