Swagger半小时入门，并足以搞定日常需求

Swagger

是什么？

号称世界上最流行的api文档生成工具.

Swagger挂网

能干嘛？

RestFul Api 文档在线自动生成工具，，API文档与api定义同步更新
直接运行，可以在线测试api接口
支持多种语言

将代码中的接口生成可视化的api文档
控制器代码

生成的api文档

怎么玩

在项目中使用swagger

pom文件导入依赖的jar包

swagger2
ui

---

springboot集成swagger

1. 创建springboot web项目

本项目github地址: https://github.com/resuper/springboot-swagger-demo.git

2. pom文件导入依赖

        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-swagger2artifactId>
            <version>2.9.2version>
        dependency>

        
        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-swagger-uiartifactId>
            <version>2.9.2version>
        dependency>

3. 配置Swagger

@Configuration
@EnableSwagger2
public class SwqggerConfig {
    
}

测试

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

项目路径 + swagger-ui.html
能看到长这个样子的页面就行，我这里做了其他配置所以会有些区别。

---

配置Swagger标题等信息

	@Bean
    public Docket docket(Environment environment){
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo());
    }
	
    /**
     * 配置标题等信息
     * @return
     */
    private ApiInfo apiInfo(){
    return new ApiInfo("Api Documentation 我的标题",
                       "Api Documentation------描述",
                       "1.0vvvvv",
                       "https://me.csdn.net/resuper0",
                       DEFAULT_CONTACT, "Apache 2.0",
                       "http://www.apache.org/licenses/LICENSE-2.0",
                       new ArrayList());
}

配置扫描接口（控制器）

new Docket(DocumentationType.SWAGGER_2)
                .select()
//                .apis(RequestHandlerSelectors.basePackage(("com.resuper.controller")))
                .apis(RequestHandlerSelectors.any())
                .build();

配置是否启动swagger

docket.enable(bool)

//通过配置文件获取是生产环境还是开发环境，
//根据不同环境配置是否开启swagger

	@Bean
    public Docket docket(Environment environment){
        // 设置要显示swagger的环境
        Profiles profiles = Profiles.of("dev","test");

        // 判断当前环境是否处于指定的环境列表中
        boolean environmentFlag  = environment.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                // 根据环境配置是否要显示swagger
                .enable(environmentFlag);
    }

配置多个分组

	@Bean
    public Docket docket2(Environment environment){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("张云越");
    }
    @Bean
    public Docket docket4(Environment environment){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("张兴佑");
    }
    @Bean
    public Docket docket5(Environment environment){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("项目经理");
    }
    @Bean
    public Docket docket6(Environment environment){
        return new Docket(DocumentationType.SWAGGER_2)
                .groupName("运维组");
    }
              

实体类配置

1. controller的返回值如果包含某个类，那么model就会包含这个类
    
    
 2.注解

@ApiModel("用户实体类")
public class User {
    private Integer id;
    @ApiModelProperty("用户名")
    private String userName;
    @ApiModelProperty("密码")
    private String password;
    @ApiModelProperty("地址")
    private String address;

}

注释

@ApiModelXXX("注释")


//多把时间用在更有意义的事情上，如果不是公司硬性规定，这种没太大意义的注释……
//小声bb：“看不懂算求”

测试

在页面上便可以测试，不过我还是喜欢postman，一个发送请求的男人

总结

• 可以用swagger给难以理解的接口添加注释
• 接口文档实时更新
• 可以在线测试
• 主要用于前后端分离的项目

挖槽，Swagger是一个很优秀的工具，很多大公司都在使用！

• 再也不用和前端小哥哥小姐姐因为接口争吵了。

在正式发布的时候，需要关闭Swagger！！！！！

出于安全考虑，还节省内存