Swagger2的使用

逃离我推掉我的手 2023-10-01 09:13 5阅读 0赞

这不做基本介绍了,新手只需要知道是一个接口文档规范,按照它的规范(注解形式)能自动生成web形式接口文档,通过url都前后端都可以访问,方便数据交互就可以了,重点在于使用

spring boot 中swagger2的依赖

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

spring boot已经整合了swagger,就是springfox,其作用就是生成接口文档,简化开发.  
还有一个依赖是

<dependency>
    			<groupId>com.mangofactory</groupId>
    			<artifactId>swagger-springmvc</artifactId>
    			<version>0.9.5</version>
    		</dependency>

springfox就是由swagger-spingmvc发展而来,前者自然比后者更强大更适用.

在这里只是实用的例子,基本开发够用,想深入,去官网

[springfox官网链接][springfox]

导入依赖后,首先要做的就是写一个配置类(复制粘贴下方代码,日常开发基本可以满足,要求比较高的话可查官网增加配置)

import io.swagger.annotations.ApiOperation;
    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;
    import java.util.HashSet;
    import java.util.Set;
    
    @Configuration
    @EnableSwagger2
    public class SwaggerConfiguration {
        
        @Bean
        public Docket createRestApi() {
        
            Set<String> producesList = new HashSet<>();
            producesList.add("application/json");
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .produces(producesList)
                    .select()
                    .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                    .paths(PathSelectors.any())
                    .build();
        }
        
        //文档信息说明和个人信息配置
        private ApiInfo apiInfo() {
        
            return new ApiInfoBuilder()
                    .title("我的swagger")
                    .description("我的的描述")
                    .contact(new Contact("我的邮箱", "", "xxxxxxxx@163.com"))
                    .version("1.0")
                    .build();
        }
    }

写完配置类后,启动application就可以访问swagger web页面了,  
swagger web页面地址(接口文档):**http://localhost:8080/swagger-ui.html**  
我们的接口文档的雏形也就出来了 apiInfo()方法中定义的内容,可对比下图  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI4NjAzMTI3_size_16_color_FFFFFF_t_70]  
接口文档雏形已经有了,剩下的就是接口实际对接参数了.

@Api(value = "Api value啊", tags = {
        "Api tags啊"})
    @RestController
    @RequestMapping("/account")
    public class AccountController {
        
    
    }

上方是一个controller  
@Api注解是swagger注解,作用就是对于当前的controller做一个说明  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI4NjAzMTI3_size_16_color_FFFFFF_t_70 1]  
下方是一个controller中的一个方法

@ApiOperation(value = "ApiOperation Value啊", notes = "ApiOperation Note啊")
        @ApiImplicitParams({
        
                @ApiImplicitParam(name = "id", value = "用户编号", required = true,dataType = "long"),
                @ApiImplicitParam(name = "name", value = "用户名", required = false)
        })
        @RequestMapping(value = "/swagger", method = RequestMethod.GET)
        public String swaggerTest(@RequestParam("id") Long id, @RequestParam("name") String name) {
        
            return name + ":" + id;
        }

@ApiOperation 是非常重要的一个注解,作用于方法上,用来做方法的说明  
比如@ApiOperation(values = “获取用户信息”) 前端很容易就可以知道,获取用户信息要调用这个接口.其中的notes是注意事项,也可以理解成描述,可以将请求参数等信息直接用文字写到里面,虽然不正式,但是如果能说明白,也可以不需要再用  
@ApiImplicitParam @ApiImplicitParams @ApiParam等注解再对参数进行说明,偷懒时候可以这么干.  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI4NjAzMTI3_size_16_color_FFFFFF_t_70 2]  
@ApiImplicitParams相当于 @ApiImplicitParam集合  
@ApiImplicitParam是对入参进行说明,但是只是对单个参数说明,比如long id  
就用@ApiImplicitParam(name = “id”,value=“用户编号”, required = true,dataType = “long”) name 必须等于参数名,value是参数说明.还有一个参数是String name 就再用一个注解去说明.但是如果是一个自动封装的Bean对象,比如Test test 这个注解就不能说明出Test对象中每一个属性了,也就是@ApiImplicitParam注解只能说明当前对象,但是对向前对象内部结构无法说明,后面会讲解.  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI4NjAzMTI3_size_16_color_FFFFFF_t_70 3]

@ApiParam注解作用基本等同于@ApiImplicitParam

@ApiOperation(value = "swagger啊", notes = "swagger1注意事项")
        @RequestMapping(value = "/swagger1", method = RequestMethod.GET)
        public String swaggerTest1(@RequestParam("id")  @ApiParam(name="用户编号",value="用户号编号说明",required=true)Long id,
                                   @RequestParam("name")  @ApiParam(name="用户名字",value="用户名字说明",required=true) String name) {
        
            return name + ":" + id;
        }
    123456

它作用在参数上,也是对参数的说明,@ApiParam中name可以不是参数名,value是对参数的描述,所以选择用@ApiParam还是@ApiImplicitParam 可以自己决定,不过我比较推荐,基本数据类型用@ApiImplicitParam, Bean类型用@ApiParam.  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI4NjAzMTI3_size_16_color_FFFFFF_t_70 4]

最后一个方法

@ApiOperation(value = "swagger2啊", notes = "swagger2注意事项")
        @RequestMapping(value = "/swagger2", method = RequestMethod.POST)
        public String swaggerTest2(@RequestBody @ApiParam(name="用户对象",value="用户对象说明",required=true) Test test) {
        
            return test.getString2() + ":" + test.getString1();
        }

这样子只能对于test这个对象进行说明,但是内部属性,没有办法说明,因为我们是json自动转对象,所以有必要说明下test中每个字段,前端也好传参,要说明自定义对象,需要用@ApiModel 和@ApiModelProperty 注解

@ApiModel(value="test对象",description="test测试")
    public class Test {
        
       @ApiModelProperty(
               name = "string1",
               value = "第一个string",
               dataType = "String",
               example = "string1example",
               required = true)
       private String string1;
    
       @ApiModelProperty(
               name = "string2",
               value = "第二个string",
               dataType = "String",
               example = "string2example",
               required = false
       )
       private String string2;
    
    ///getter setter toString
    
    }

@ApiModel注解作用于类上,是对类的说明,@ApiModelProperty是对属性的说明  
![在这里插入图片描述][watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI4NjAzMTI3_size_16_color_FFFFFF_t_70 5]  
以上就是springfox(swagger)的基本使用,开发中用的最多的几个注解已经说明了,至于其他的注解我现在基本不用,所以不再说明.要学习springfox,就多写几个接口,用几次注解,熟悉一下web 页面,很快就可以学会~

[springfox]: http://springfox.github.io/springfox/
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI4NjAzMTI3_size_16_color_FFFFFF_t_70]: https://img-blog.csdnimg.cn/20191210153859660.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI4NjAzMTI3,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI4NjAzMTI3_size_16_color_FFFFFF_t_70 1]: https://img-blog.csdnimg.cn/201912101706288.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI4NjAzMTI3,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI4NjAzMTI3_size_16_color_FFFFFF_t_70 2]: https://img-blog.csdnimg.cn/20191210170437962.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI4NjAzMTI3,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI4NjAzMTI3_size_16_color_FFFFFF_t_70 3]: https://img-blog.csdnimg.cn/20191210162345829.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI4NjAzMTI3,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI4NjAzMTI3_size_16_color_FFFFFF_t_70 4]: https://img-blog.csdnimg.cn/20191210163519958.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI4NjAzMTI3,size_16,color_FFFFFF,t_70
[watermark_type_ZmFuZ3poZW5naGVpdGk_shadow_10_text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI4NjAzMTI3_size_16_color_FFFFFF_t_70 5]: https://img-blog.csdnimg.cn/20191211102041679.png?x-oss-process=image/watermark,type_ZmFuZ3poZW5naGVpdGk,shadow_10,text_aHR0cHM6Ly9ibG9nLmNzZG4ubmV0L3FxXzI4NjAzMTI3,size_16,color_FFFFFF,t_70