swagger2pro 后端接口生成文档

1. swagger2是什么
   swagger是一个RESTFUL 接口的文档在线自动生成和功能测试的框架

2. Springboot整合Swagger2
   1.创建springboot项目
   2.添加依赖
       <!-- Swagger API文档 -->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.9.2</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.9.2</version>
        </dependency>
   3.添加Swagger2配置类SwaggerConfig
     注1：修改扫描包名
   4.API接口编写
   5.SpringBoot启动成功后，访问http://localhost:8080/swagger-ui.html即可

3.swagger2常用注解  
@Api：用在类上，说明该类的作用。
@ApiOperation：注解来给API增加方法说明。
@ApiImplicitParams : 用在方法上包含一组参数说明。
@ApiImplicitParam：用来注解来给方法入参增加说明。
@ApiResponses：用于表示一组响应
@ApiResponse：用在@ApiResponses中，一般用于表达一个错误的响应信息
@ApiModel：描述一个Model的信息（一般用在请求参数无法使用@ApiImplicitParam注解进行描述的时候）
@ApiModelProperty：描述一个model的属性
其中
@ApiResponse参数：

code：数字，如400
message：信息，如“参数填写错误”
response：抛出异常的类
@ApiImplicitParam参数：
paramTpye：指定参数放在哪些地方（header/query/path/body/form）
name：参数名
dataTpye：参数类型
required：是否必输（true/false）
value：说明参数的意思
defaultValue：参数默认值
   

4.Swagger在生产环境无法使用
    为了保证接口文档的安全，禁用了生产环境的加载，具体说明请看：https://sns.bladex.vip/q-39.html

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

定义了只有dev和test环境才会加载swagger，所以如果你部署起来需要放开端口，请把环境设置成test，prod为了安全性是强制不让开的

blade-tool的blade-core-swagger有个SwaggerAutoConfiguration配置，如下：

/**
 * swagger配置
 *
 * @author Chill
 */
@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
@Profile({"dev", "test"})
@EnableConfigurationProperties(SwaggerProperties.class)
public class SwaggerAutoConfiguration

<!-- swagger2  一个做ui 一个做提供接口的-->
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>2.8.0</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>2.8.0</version>
        </dependency>

注1：在 Security 中的配置
Spring Boot 项目中如果集成了 Spring Security，在不做额外配置的情况下，Swagger2 文档会被拦截。
解决方法是在 Security 的配置类中重写 configure 方法添加白名单即可：
@Override
public void configure ( WebSecurity web) throws Exception {
    web.ignoring()
      .antMatchers("/swagger-ui.html")
      .antMatchers("/v2/**")
      .antMatchers("/swagger-resources/**");
}

附录X：前后端分离，如何维护接口文档 ?
前后端分离开发日益流行，大部分情况下，我们都是通过 Spring Boot 做前后端分离开发，
前后端分离一定会有接口文档，不然会前后端会深深陷入到扯皮中。一个比较笨的方法就是使用 word 或者 md 来维护接口文档，
但是效率太低，接口一变，所有人手上的文档都得变。在 Spring Boot 中，这个问题常见的解决方案是 Swagger ，
使用 Swagger 我们可以快速生成一个接口文档网站，接口一旦发生变化，文档就会自动更新，
所有开发工程师访问这一个在线网站就可以获取到最新的接口文档，非常方便。