【SpringBoot】swagger 快速上手的两种使用方法

红太狼 2022-12-20 05:59 148阅读 0赞

# 效果图 #

![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MzQ2OTY4MA_size_16_color_FFFFFF_t_70_pic_center]

# 一：swagger是什么？ #

1、是一款让你更好的书写API文档的规范且完整框架。

2、提供描述、生产、消费和可视化RESTful Web Service。

3、是由庞大工具集合支撑的形式化规范。这个集合涵盖了从终端用户接口、底层代码库到商业API管理的方方面面。

# 二：使用 #

## 方法一：使用第三方依赖（最简单的方法） ##

1、在pom.xml文件中添加第三方swagger依赖（）

<dependency>
    		<groupId>com.spring4all</groupId>
    		<artifactId>swagger-spring-boot-starter</artifactId>
    		<version>1.7.0.RELEASE</version>
    	</dependency>

2、在Spring Boot项目的启动类上添加@EnableSwagger2Doc注解，就可以直接使用啦。  
3、[https://github.com/SpringForAll/spring-boot-starter-swagger][https_github.com_SpringForAll_spring-boot-starter-swagger]这是GitHub上这个swagger依赖实现的项目，里面有详细的讲解。

## 方法二：使用官方依赖+配置类 ##

1、在pom.xml文件中添加swagger相关依赖

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

第一个是API获取的包，第二是官方给出的一个ui界面。这个界面可以自定义，默认是官方的，对于安全问题，以及ui路由设置需要着重思考。  
2、 开启启动类application`@EnableSwagger2` 或者在3中直接填写  
3、swagger的configuration

需要特别注意的是swagger scan base package,这是扫描注解的配置，即你的API接口位置。

package com.bennyrhys.mall.config;
    
    import org.springframework.context.annotation.Bean;
    import org.springframework.context.annotation.Configuration;
    import springfox.documentation.builders.ApiInfoBuilder;
    import springfox.documentation.builders.PathSelectors;
    import springfox.documentation.builders.RequestHandlerSelectors;
    import springfox.documentation.service.ApiInfo;
    import springfox.documentation.service.Contact;
    import springfox.documentation.spi.DocumentationType;
    import springfox.documentation.spring.web.plugins.Docket;
    import springfox.documentation.swagger2.annotations.EnableSwagger2;
    
    @EnableSwagger2
    @Configuration
    public class SpringFoxConfig { 
    
        //访问http://localhost:8080/swagger-ui.html可以看到API文档
        @Bean
        public Docket api() { 
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.any()) // .apis(RequestHandlerSelectors.basePackage("com.bennyrhys.swagger"))
                    .paths(PathSelectors.any())
                    .build();
        }
    
        private ApiInfo apiInfo() { 
            return new ApiInfoBuilder()
                    .title("慕慕生鲜")
                    .description("详细描述")
                    .contact(new Contact("bennyrhys", "htpps://xxx", "bennyrhys@163.com"))
                    // .version("v1.0.0")
                    .license("v1.0.0-Apache2.0")
                    .termsOfServiceUrl("")
                    .build();
        }
    }

4、可选地址映射

package com.bennyrhys.mall.config;
    
    import com.bennyrhys.mall.comm.Constant;
    import org.springframework.context.annotation.Configuration;
    import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
    import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
    
    /** * 描述： 配置地址映射 */
    @Configuration
    public class MallWebMvcConfig implements WebMvcConfigurer { 
    
        @Override
        public void addResourceHandlers(ResourceHandlerRegistry registry) { 
    // registry.addResourceHandler("/admin/**").addResourceLocations("classpath:/static/admin/");
    // registry.addResourceHandler("/images/**")
    // .addResourceLocations("file:" + Constant.FILE_UPLOAD_DIR);
            registry.addResourceHandler("swagger-ui.html").addResourceLocations(
                    "classpath:/META-INF/resources/");
            registry.addResourceHandler("/webjars/**").addResourceLocations(
                    "classpath:/META-INF/resources/webjars/");
        }
    }

# 具体使用 #

## 实体类 ##

描述、必填、隐藏  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MzQ2OTY4MA_size_16_color_FFFFFF_t_70_pic_center 1]

2.x版本
    /** * @Author bennyrhys */
    @ApiModel(description = "用户信息描述类")
    public class User { 
        @ApiModelProperty(value = "用户id")
        private Integer id;
        @ApiModelProperty(value = "用户名")
        private String username;
        @ApiModelProperty(value = "用户地址")
        private String address;
    
    1.x版本
    @ApiModelProperty(value = "Topic列表", required = false, hidden = true)

## controller ##

建议不加value  
加operation的描述方法  
加是否必传

// 可以不展示此接口
    // @ApiIgnore

查询，是否必要

/** * 查询用户 【页面参数query】 * @param id * @return */
        // 方法 方法描述
        @ApiOperation(value = "查询用户",notes = "根据用户id查询用户 ")
        // 参数 参数描述 参数必填【针对swagger】
    // @ApiImplicitParam(name = "id", value = "用户id", required = true, defaultValue = "99")
        @GetMapping("/user")
        public User getUserById(Integer id) { 
            User user = new User();
            user.setId(id);
            return user;
        }

删除，返回值

@ApiOperation(value = "删除用户",notes = "根据用户id删除用户")
        @ApiImplicitParam(name = "id", value = "用户id", required = true, defaultValue = "99")
        @ApiResponses({ 
                @ApiResponse(code = 200, message = "删除成功"),
                @ApiResponse(code = 500, message = "删除失败")
        })

更新，多参数

/** * 更新用户 */
        @ApiImplicitParams({ 
                @ApiImplicitParam(name = "id", value = "用户id", required = true, defaultValue = "99"),
                @ApiImplicitParam(name = "username", value = "用户名", required = true, defaultValue = "bennyrhys")
        })
        @ApiOperation(value = "更新用户",notes = "根据用户id更新用户名")

# 待完善 #

权限  
响应

[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MzQ2OTY4MA_size_16_color_FFFFFF_t_70_pic_center]: /images/20221120/aac55b3e11ec4ba09741517af5533e8d.png
[https_github.com_SpringForAll_spring-boot-starter-swagger]: https://github.com/SpringForAll/spring-boot-starter-swagger
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3dlaXhpbl80MzQ2OTY4MA_size_16_color_FFFFFF_t_70_pic_center 1]: /images/20221120/f2ce911675fa4786aea782f4d8184ec5.png