Swagger

标签：Swagger return Bean swagger Docket public

学习文档：

https://www.cnblogs.com/jiex123/p/13149453.html

https://blog.csdn.net/weixin_57259781/article/details/123506393

学习视频：https://www.bilibili.com/video/BV1Y441197Lw/

Swagger官网：https://swagger.io/

Swagger 简介：

　　Swagger 是一套围绕 Open API 规范构建的开源工具，可以帮助设计，构建，记录和使用 REST API。

　　Swagger 工具包括的组件：

　　　　Swagger Editor ：基于浏览器编辑器，可以在里面编写 Open API规范。类似 Markdown 具有实时预览描述文件的功能。

　　　　Swagger UI：将 Open API 规范呈现为交互式 API 文档。用可视化UI 展示描述文件。

　　　　Swagger Codegen：将 OpenAPI 规范生成为服务器存根和客户端库。通过 Swagger Codegen 可以将描述文件生成 html 格式和 cwiki 形式的接口文档，同时也可以生成多种言语的客户端和服务端代码。

　　　　Swagger Inspector：和 Swagger UI 有点类似，但是可以返回更多信息，也会保存请求的实际参数数据。

　　　　Swagger Hub：集成了上面所有项目的各个功能，你可以以项目和版本为单位，将你的描述文件上传到 Swagger Hub 中。在 Swagger Hub 中可以完成上面项目的所有工作，需要注册账号，分免费版和收费版。

　　　　使用 Swagger，就是把相关的信息存储在它定义的描述文件里面（yml 或 json 格式），再通过维护这个描述文件可以去更新接口文档，以及生成各端代码。

SpringBoot集成Swagger

1.导入依赖

 在pom.xml文件中导入依赖：
 <!--https://mvnrepository.com/artifact/io.springfox/springfox-swagger2-->
         <dependency>
             <groupId>io.springfox</groupId>
             <artifactId>springfox-swagger2</artifactId>
             <version>2.9.2</version>
         </dependency>
         <!--https://mvnrepository.com/artifact/io.springfox/springfox-swagger-ui-->
         <dependency>
             <groupId>io.springfox</groupId>
             <artifactId>springfox-swagger-ui</artifactId>
             <version>2.9.2</version>
         </dependency>

2.在Config包下面创建类SwaggerConfig：

 @Configuration
 @EnableSwagger2   //开启swagger2
 public class SwaggerConfig {
     
 }

3.测试运行

http://localhost:8080/swagger-ui.html

4.配置Swagger

 @Configuration
 @EnableSwagger2   //开启swagger2
 public class SwaggerConfig {
 
     //配置了swagger的Docket的bean实例
     @Bean
     public Docket docket(){//该方法返回对象为Docket,并将该对象注入到Bean里面
         return new Docket(DocumentationType.SWAGGER_2).apiInfo(apiInfo());
     }
 
     //配置swagger的信息等于apiInfo
     private ApiInfo apiInfo(){
         //作者信息
         Contact contact = new Contact("作者a","https://blog.kuangstudy.com/","邮箱");
 
         return new ApiInfo(
                 "Swagger日志",//标题
                 "nihaoya",//描述
                 "v1.0",//版本
                 "https://blog.kuangstudy.com/",//组织名或者作者信息或者博客网址(一个网址)
                 DEFAULT_CONTACT,
                 "Apache 2.0",
                 "http:www.apache.org/licenses/LICENSE-2.0",
                 new ArrayList()
         );
     };
 }

再次访问查看：

http://localhost:8080/swagger-ui.html

6.Swagger配置扫描接口

6-1.配置扫描接口Docket.select()

    //配置了swagger的Docket的bean实例
     @Bean
     public Docket docket(){//该方法返回对象为Docket,并将该对象注入到Bean里面
         return new Docket(DocumentationType.SWAGGER_2)
                 .apiInfo(apiInfo())
                 .select()
                 //RequestHandlerSelectors配置要扫描接口的方式.
                 // basePackage()表示指定要扫描的包，参数为包的路径,一般会使用的方法
                 //any()表示扫描所有的包
                 //none()表示所有包都不扫描
                 //withClassAnnotation表示扫描类上面的注解，参数为一个注解的反射对象，值可以为：@GetMapping.class
                 //withMethodAnnotation表示扫描方法上面的注解
                 //.apis(RequestHandlerSelectors.withClassAnnotation(@GetMapping.class))
                 .apis(RequestHandlerSelectors.basePackage("com.example.swaggerdemo.controller"))
                //path表示过滤,常用的为ant()
                 //.paths(PathSelectors.ant("/example/**"))
                 .build();
     }

6-2.配置是否启动swagger

    //enable为是否启动swagger，如果为false,则swagger不能在浏览器中访问
     @Bean
     public Docket docket(){//该方法返回对象为Docket,并将该对象注入到Bean里面
         return new Docket(DocumentationType.SWAGGER_2)
                 .apiInfo(apiInfo())
                 .enable(false)  
                 .select()
    .apis(RequestHandlerSelectors.basePackage("com.example.swaggerdemo.controller"))
                 .build();
     }

我的swagger在生产环境中使用，在发布的时候不使用？

判断是不是生产环境 flag=false

注入enable(flag)

进行多配置的方法:

0.在application.propeties设置

spring.profils.active=dev

1.在resources下面新建生产环境文件application-dev.properties 并输入以下内容：

server.port=8081

2.在resources下面新建生产环境文件application-pro.properties 并输入以下内容：

server.port=8082

3.SwaggerConfig设置

 //配置了swagger的Docket的bean实例
 
    @Bean
    public Docket docket(Environment environment){//该方法返回对象为Docket,并将该对象注入到Bean里面
 
        //设置要显示的swagger环境
        Profiles profiles = Profiles.of("dev","test");   //如果application.properties中配置为dev则访问

       //获取项目的环境：
        //通过environment.acceptsProfiles判断是否处在自己设定的环境中
        //如果系统检测到当前环境为dev或者test则flag为true,否则为flase
        boolean flag = environment.acceptsProfiles(profiles);
 
 
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.example.swaggerdemo.controller"))
                .build();
    }

配置API文档的分组

1.只有一个分组：在文件swaggerconfig.java中一定位置加入以下代码

 .groupName("zhangsan")//组名

2.存在多个分组时，一个Docket对象代表一个组，创建多个对象就会有多个组：

//多个组
    @Bean
    public Docket docket1(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("A");//第一个组
    }
    @Bean
    public Docket docket2(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("B");//第二个组
    }
    @Bean
    public Docket docket3(){
        return new Docket(DocumentationType.SWAGGER_2).groupName("C");//第三个组
    }

实体类配置

@ApiModel("用户实体类")//给实体类的文档注释
public class User {
 
    @ApiModelProperty("用户名")//给属性的文档注释
    public String username;
    @ApiModelProperty("密码")
    public String password;
}

@RestController
public class HelloController {
 
//    @RequestMapping("/hello")
//    public String hello(){
//        return "hello";
//    }
 
    @GetMapping("/hello")
    public String hello(){
        return "hello";
    }
 
    //只要我们的接口中，返回值存在实体类，它就会被扫描到Swagger中
    @PostMapping("/user")
    public User user(){
        return new User();
    }
 
    //Operation接口,不是放在类上，而是放在接口上
    @ApiOperation("hello控制类")
    @GetMapping("/hello2")
   public String hello2(@ApiParam("这是用户名") String username){//@ApiParam("用户名")为参数的注释
        return "hello"+username;
    }
}

总结：

可以通过Swagger给一些比较难以理解的属性或者接口，增加注释信息
接口文档实时更新
可以在线测试
注意点：在正式发布的时候，关闭swagger.出于安全考虑，节省内存。

标签：Swagger,return,Bean,swagger,Docket,public
From： https://www.cnblogs.com/xinyu-yudian/p/16905643.html

配置API文档的分组

实体类配置

相关文章

赞助商

阅读排行