swagger2使用教程（swagger2的使用）



swagger2是一个规范和完整的框架，用于生成、描述、调用和可视化Restful风格的web服务，现在我们使用springboot整合他

作用：

• 接口的文档在线自动生成
• 功能测试

swagger的优势

• 支持API自动生成同步的在线文档：使用swagger后可以直接通过代码生成文档，不再需要自己手动编写接口文档了，对程序员来说非常方便，可以节约写文档的时间去学习新技术。
• 提供web页面在线测试API：光有文档还不够，swagger生成的文档还支持在线测试。参数和格式都定义好了，直接在页面输入参数对应的值即可在线测试接口。

在配置文件config目录下，添加swagger的配置文件swaggerConfig.java

@Configuration // 配置类 @EnableSwagger2 // 开启 swagger2 的自动配置 public class SwaggerConfig { }

这个时候 Swagger 已经算是整合到项目之中了，可以启动下服务，输入：http://localhost:8080/swagger-ui.html# （这里我的项目端口是 8868 ，项目路径是 /mike，所以我打开的文档地址为 http://localhost:8868/mike/swagger-ui.html# ）即可查看 swagger 文档。

可以看到 Swagger 文档中大概有这四类信息

组 基本信息 接口信息 实体类信息

配置基本信息

   @Bean    public Docket docket() {        // 创建一个 swagger 的 bean 实例        return new Docket(DocumentationType.SWAGGER_2)                // 配置基本信息               .apiInfo(apiInfo())               ;   } ​    // 基本信息设置    private ApiInfo apiInfo() {        Contact contact = new Contact(                "米大傻", // 作者姓名                "https://blog.csdn.net/xhmico?type=blog", // 作者网址                "@163.com"); // 作者邮箱        return new ApiInfoBuilder()               .title("多加辣-接口文档") // 标题               .description("众里寻他千百度，慕然回首那人却在灯火阑珊处") // 描述               .termsOfServiceUrl("https://www.baidu.com") // 跳转连接               .version("1.0") // 版本               .license("Swagger-的使用(详细教程)")               .licenseUrl("https://blog.csdn.net/xhmico/article/details/")               .contact(contact)               .build();   }

Swagger 默认只有一个 default 分组选项，如果没有设置，所有的接口都会显示在 default `分组下，如果功能模块和接口数量一多，就会显得比较凌乱，不方便查找和使用。swagger 文档中组名默认是 default，可通过 .groupName(String )

 @Bean    public Docket docket() {        // 创建一个 swagger 的 bean 实例        return new Docket(DocumentationType.SWAGGER_2)               .groupName("mike"); // 修改组名为 "mike"                   }

如果需要配置多个组的话，就需要配置多个docker()

    /     * 展示 controller 包下所有的接口     */    @Bean    public Docket docket1() {        // 创建一个 swagger 的 bean 实例        return new Docket(DocumentationType.SWAGGER_2)               .groupName("mike") // 修改组名为 "mike"                // 配置接口信息               .select() // 设置扫描接口                // 配置如何扫描接口               .apis(RequestHandlerSelectors                       .basePackage("com.duojiala.mikeboot.controller") // 扫描指定包下的接口，最为常用               )               .paths(PathSelectors                         .any() // 满足条件的路径，该断言总为true               )               .build();   } ​    /     * 展示路径为 /error 的所有接口（基础接口）     */    @Bean    public Docket docket2() {        // 创建一个 swagger 的 bean 实例        return new Docket(DocumentationType.SWAGGER_2)               .groupName("yank") // 修改组名为 "yank"                // 配置接口信息               .select() // 设置扫描接口                // 配置如何扫描接口               .apis(RequestHandlerSelectors                       .any() // 扫描全部的接口，默认               )               .paths(PathSelectors                       .ant("/error") // 满足字符串表达式路径               )               .build();   }

一般生产环境是不能放开swagger的，这样接口暴露在外网很不安全!!

在开发或者测试环境下，我们开启swagger会方便前端和后端的交互，但是如果在生产环境下也开启swagger的话，是会将接口暴露出去的，有极大风险，如何让swagger根据不同的环境来决定是否开启

这里我准备了四个项目的配置文件，、、 三个环境的配置文件仅是端口上的不同

• application.yml -------------------------- 全局配置文件
• application-dev.yml -------------------- 开发环境配置文件
• application-test.yml -------------------- 测试环境配置文件
• application-pro.yml -------------------- 生产环境配置文件

可以通过代码判断此时是在什么环境：、、，如果是在 生产环境，则关闭 swagger。

添加@Profile注解，指明在何种环境下可以使用Swagger2，一般情况下只有在开发(dev)和测试(test)环境下才可以使用Swagger2；而在生产(dev)环境下不能使用Swagger2

@Configuration
//开启Swagger2
@EnableSwagger2
//配置生产环境下不可用  dev(开发)、test(测试)、prod(生产)
@Profile({"dev","test"})
public class Swagger2Configuration extends WebMvcConfigurationSupport { 
    ...
 
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("doc.html")
.addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/")
.addResourceLocations("classpath:/META-INF/resources/webjars/");
    }
}

application.yml内容如下，用于指定选择的环境：

spring:  profiles:    active: dev

​ <dependency>    <groupId>io.springfox</groupId>    <artifactId>springfox-swagger2</artifactId>    <version>2.9.2</version>    <exclusions>        <exclusion>            <artifactId>swagger-models</artifactId>            <groupId>io.swagger</groupId>        </exclusion>    </exclusions> </dependency> • <dependency>    <groupId>com.github.xiaoymin</groupId>    <artifactId>swagger-bootstrap-ui</artifactId>    <version>1.8.5</version> </dependency> • <!-- 使用1.5.22--> <dependency>    <groupId>io.swagger</groupId>    <artifactId>swagger-models</artifactId>    <version>1.5.22</version> </dependency>

​
@Configuration
//开启Swagger2
@EnableSwagger2
//配置生产环境下不可用  dev(开发)、test(测试)、prod(生产)
@Profile({"dev","test"})
public class Swagger2Configuration extends WebMvcConfigurationSupport {
    //api接口包扫描路径
    public static final String
            SWAGGER_SCAN_BASE_PACKAGE = "com.lky.swagger2pro.controller";
    //指定当前Swagger API文档版本
    public static final String VERSION = "1.0.0";
•
    /
     * 创建API应用
     * apiInfo() 增加API相关信息
     * 通过select()函数返回一个ApiSelectorBuilder实例,用来控制哪些接口暴露给Swagger来展现，
     * 本例采用指定扫描的包路径来定义指定要建立API的目录。
     * @return
     */
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                // 接口文档的基本信息
                .apiInfo(apiInfo())
                .select()
                // 方法需要有ApiOperation注解才能生存接口文档
                //.apis(RequestHandlerSelectors.basePackage(SWAGGER_SCAN_BASE_PACKAGE))
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                // 路径使用any风格
                .paths(PathSelectors.any())
                .build();
    }
•
    /
     * 创建该API的基本信息（这些基本信息会展现在文档页面中）
     * 访问地址：http://项目实际地址/doc.html
     * @return
     */
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("SpringBoot中使用Swagger2构建RestFul APIs")
                .description("测试系统")
                //.termsOfServiceUrl("http://www..com")
                .version(VERSION)
                .build();
    }
•
    @Override
    protected void addResourceHandlers(ResourceHandlerRegistry registry) {
        registry.addResourceHandler("doc.html").addResourceLocations("classpath:/META-INF/resources/");
        registry.addResourceHandler("/webjars/").addResourceLocations("classpath:/META-INF/resources/webjars/");
    }

paramType

​    @ResponseBody    @RequestMapping(value="findResumeByCand",method = RequestMethod.POST)    @ApiOperation(value = "多条件查询")    @ApiImplicitParams({            @ApiImplicitParam(value="姓名",name="name",dataType="Stirng",paramType = "query"),            @ApiImplicitParam(value="简历状态",name="status",dataType="Stirng",paramType = "query"),            @ApiImplicitParam(value="简历来源",name="source",dataType="Stirng",paramType = "query"),            @ApiImplicitParam(value="开始时间",name="startTime",dataType="Stirng",paramType = "query"),            @ApiImplicitParam(value="结束时间",name="endTime",dataType="Stirng",paramType = "query")   })    public DataResult findResumeByCand(String name,String status,String source,String startTime,String endTime){               }   }

@ApiModel注解描述一个Model的信息（这种一般用在post创建的时候，使用@RequestBody这样的场景，请求参数无法使用 @ApiImplicitParam注解进行描述的时候）

@ApiModelProperty注解描述一个model的属性

打开CMD，跳转到target目录，输入命令：java -jar .xxx.jar --spring.profiles.active=prod。可以直接打开jar包修改application.yml配置文件中spring.profiles.active属性切换运行环境，具体请参考以下配置

开发环境：dev；

生产环境：prod；

测试环境：test；

版权声明：

本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。
如若内容造成侵权、违法违规、事实不符，请将相关资料发送至xkadmin@xkablog.com进行投诉反馈，一经查实，立即处理！

转载请注明出处，原文链接：https://www.xkablog.com/rfx/17850.html