docker swarm yaml版本

SpringBoot下Swagger快速入门使用

---

文章目录

• SpringBoot下Swagger快速入门使用

• @[toc]

• 1、swagger初识
• 2、Swagger快速开始
• 3、Swagger的使用配置
• 4、swagger注释注解

1、swagger初识

---

• 1、前导知识

• 前后端开发阶段：

• 大后端时代：前端设计静态页面，后端使用模板引擎实现动态展示；主要开发点在后端代码上。
• 前后端分离：
  前端：前端不再需要后端代码即可运行部署；其开发分为：前端控制层、视图层。
  后端：后端控制层、服务层、数据访问层。

• 前后端开发联调问题：

• 前端人员和后端人员无法实时协商，尽快解决（比如前端后续更新，添加了新功能展示，需要通知后端人员提供新的接口），开发难度变大。

• 解决方案

• 制定计划大纲，及时更新最新api。

• 早期：使用word文档完成。
• 中期：使用各种接口测试工具

• 例如：前端使用postman测试，后端提供最新接口。

• 使用swagger

• 2、Swagger 官网：API Documentation & Design Tools for Teams | Swagger

• 定义： 是一个api框架，RestFul api 文档在线生成工具。利用代码在线生成接口说明文档，且可以在线测试。
• 好处：

• 后端：

• 不用再手写WiKi接口拼大量的参数，避免手写错误
• 对代码侵入性低，采用全注解的方式，开发简单
• 方法参数名修改、增加、减少参数都可以直接生效，不用手动维护
• 缺点：增加了开发成本，写接口还得再写一套参数配置

• 前端：

• 后端只需要定义好接口，会自动生成文档，接口功能、参数一目了然
• 联调方便，如果出问题，直接测试接口，实时检查参数和返回值,就可以快速定位是前端还是后端的问题

• 测试：

• 对于某些没有前端界面UI的功能，可以用它来测试接口
• 操作简单，不用了解具体代码就可以操作
• 操作简单，不用了解具体代码就可以操作

• 支持java、php等语言。

---

2、Swagger快速开始

---

• 1、使用三步走

• 1）导入依赖

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

• 2）配置：默认配置。

@Configuration
@EnableSwagger2 //开启使用swagger2（swagger是老版的）
public class SwaggerConfiguration {//使用默认配置
}

• 3）使用
  访问：http://localhost:8080/swagger-ui.html

---

3、Swagger的使用配置

---

• 1、使用swagger的实例docket配置基础信息

@Configuration
@EnableSwagger2 //开启使用swagger2（swagger是老版的）
public class SwaggerConfiguration {//使用自定义配置
    
    //使用docket实例用于取代swagger原本的配置。
    @Bean
    public Docket docket () {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
            	.groupName("grp1")//设置分组
            	.enable(true)
            	.select()
          	.apis(RequestHandlerSelectors.basePackage("com.zm.controller"))
            	.paths(PathSelectors.any())
            	.build();
    }
    
    private ApiInfo apiInfo() {
        
        Contact DEFAULT_CONTACT = new Contact("作者名:zm", "指定的某个url", "作者email");
        
        return new ApiInfo("标题：我的Swagger-Api文档", 
                           "本文档描述信息", "版本：1.0", 
                           "项目组织网址（一个url）", 
                           DEFAULT_CONTACT, 
                           "Apache 2.0", 
                           "http://www.apache.org/licenses/LICENSE-2.0", new ArrayList());
    }
}

Docket对象说明：

• 1）构造方法：需要一个DocumentationType类对象，这里选择SWAGGER_2

• 2）apiInfo()：用于配置swagger 信息。

这个类对象仅有如下属性，且只有一个构造方法。

官方提供了一个默认对象的构造方法，在该类的静态代码块中。

我们可以参照其创建一个apiInfo实例。

• 3）apiInfo中的contact对象：用于配置作者信息。

同样的，再ApiInfo类中同样提供了Contac类对象的构造。

• 2、使用swagger的实例docket配置扫描接口
  用法：使用docket对象的select()进行构造配置。

@Configuration
@EnableSwagger2 //开启使用swagger2（swagger是老版的）
public class SwaggerConfiguration {//使用自定义配置
    
    //使用docket实例用于取代swagger原本的配置。
    @Bean
    public Docket docket () {
        return new Docket(DocumentationType.SWAGGER_2)
                ......
            	.select()
          	.apis(RequestHandlerSelectors.basePackage("com.zm.controller"))
            	.paths(PathSelectors.any())
            	.build();
    }
    
    private ApiInfo apiInfo() {
     ......
    }
}

• 1）select().xxx（链式构造）.build()：
  这里select方法执行使用了建造者模式，最后使用build方法返回Docket对象。

这里select()返回对象可进行两步构造

• 1）apis()：用于配置要扫描接口的方式，其接受参数是一个函数式接口：Predicate selector。
  这里使用RequestHandlerSelectors.basePackage配置为扫描包：

• 2）paths()：用于配置过滤路径，其接受参数是一个函数式接口：Predicate selector。
  这里使用PathSelectors.ant(“/book/**”)，表示筛选com.zm.controller包下访问接口为/book/下的接口。

• 3、使用swagger的实例docket配置的启动与关闭

......
public class SwaggerConfiguration {//使用自定义配置
    @Bean
    public Docket docket () {
        return new Docket(DocumentationType.SWAGGER_2)
                ......
            	.enable(true)
            	.select()
          		......
            	.build();
    }
    
    private ApiInfo apiInfo() {
       ......
    }
}

• 使用enable(boolean)：默认为true代表配置有效，可修改为false。

实际作用：在生产和发布的不同环境下，希望swagger在生产环境中生效，发布环境中无效。

• 1）判断当前使用环境
• 2）读取配置
  这里提供两种方法：

//1、
@Bean
    public Docket createRestApi(Environment env) {
        //显示swagger环境
        Profiles profiles = Profiles.of("dev");
        //判断当前环境
        boolean flag = env.acceptsProfiles(profiles);

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
            	.enable(flag)
                .apis(RequestHandlerSelectors.basePackage("com.wz.controller"))
                .paths(PathSelectors.any())
                .build();
    }

//2、
@Value("${spring.profiles.active}")
private String activated;
 @Bean
    public Docket createRestApi(Environment env) {
        //判断当前环境
        boolean flag = activated.equals("dev") ? true : false;

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .enable(flag)
                .select()
                .apis(RequestHandlerSelectors.basePackage("com.wz.controller"))
                .paths(PathSelectors.any())
                .build();
    }

• 4、使用swagger的实例docket配置的分组

@Configuration
@EnableSwagger2 //开启使用swagger2（swagger是老版的）
public class SwaggerConfiguration {//使用自定义配置
    
    //使用docket实例用于取代swagger原本的配置。
    @Bean
    public Docket docket () {
        return new Docket(DocumentationType.SWAGGER_2)
                ......
            	.groupName("grp1")//设置分组
            	.select()
				......
            	.build();
    }
    
    private ApiInfo apiInfo() {
     ......
    }
}

• groupName(“grp1”)：用于设置分组,同一配置类下可以有多个docket，每个docket拥有一个组。

---

4、swagger注释注解

---

• @ApiModel(“xxx”)：给控制层返回的实体类对象添加注释
• @ApiModelProperty(“xxx”)：给字段添加注释
• @Api(“xxx”)：作用在控制层类上
• @ApiOperation(“xxx”)：作用于方法添加注释
• @ApiParam(“xxx”)：作用于控制层接口参数添加注释

---