2020-12-15

自己手动 配置 springboot swagger

官网
http://swagger.io/
先上效果图
原生访问：项目端口:服务名/swagger-ui.html
访问路径：项目端口:服务名/doc.html

标题1.导入Swagger的Jar包

包含了原生和 xiaoymin的包。
xiaoymin ui效果比较

<dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-annotations</artifactId>
            <version>1.5.22</version>
        </dependency>
        <dependency>
            <groupId>io.swagger</groupId>
            <artifactId>swagger-models</artifactId>
            <version>1.5.22</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>com.github.xiaoymin</groupId>
            <artifactId>swagger-bootstrap-ui</artifactId>
            <version>1.9.5</version>
        </dependency>

标题2.配置文件 SwaggerConfig.java

原生访问：项目端口:服务名/swagger-ui.html
访问路径：项目端口:服务名/doc.html
跟下面的配置文件中配置的路径关系不大。

import com.ccznai.common.constant.Constant;
import com.github.xiaoymin.swaggerbootstrapui.annotations.EnableSwaggerBootstrapUI;
import io.swagger.annotations.ApiOperation;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.ApiKey;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;

import java.util.List;

import static com.google.common.collect.Lists.newArrayList;

/**
 * Swagger配置
 *
 * 
 */
@Configuration
@EnableSwagger2
@EnableSwaggerBootstrapUI
public class SwaggerConfig{

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
            .apiInfo(apiInfo())
            .select()
            //加了ApiOperation注解的类，生成接口文档
            .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
            //包下的类，生成接口文档
            //.apis(RequestHandlerSelectors.basePackage("com.ccznai.modules.job.controller"))
            .paths(PathSelectors.any())
            .build()
            .directModelSubstitute(java.util.Date.class, String.class)
            .securitySchemes(security());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
            .title("标题-xxxx系统——API文档")
            .description("简介：-xxxx系统——API文档")
            .termsOfServiceUrl("http://127.0.0.1:8080/xxx/doc.html")
            .version("2.0.0")
            .build();
    }

    private List<ApiKey> security() {
        return newArrayList(
            new ApiKey(Constant.TOKEN_HEADER, Constant.TOKEN_HEADER, "header")
        );
    }
}

对接口和实体类添加注释，生成doc。常用的标记如下

@Api()用于类；
标识这个类是swagger的资源
　　tags–表示分组说明标签

@ApiOperation()用于方法；
表示一个http请求的操作
　　value用于方法描述

notes用于提示内容

@ApiModel()用于实体类
表示对类进行说明，用于参数用实体类接收

  value–表示对象名 
  description–描述

@ApiModelProperty()用于实体类字段
表示对model属性的说明或者数据操作更改
　　value–字段说明
　　name–重写属性名字
　　dataType–重写属性类型
　　required–是否必填
　　example–举例说明
　　hidden–隐藏

@ApiImplicitParam() 用于 controller 方法
表示单独的请求参数
　　name–参数ming
　　value–参数说明
　　dataType–数据类型
　　paramType–参数类型
　　example–举例说明

@ApiImplicitParams() 用于 controller 方法，包含多个 @ApiImplicitParam

@ApiIgnore()用于类或者方法上，可以不被swagger显示在页面上

说明：简单的标记只需要@Api(tags="") 和 @ApiOperation(value="",notes="")

标题4.测试地址

原生访问：项目端口:服务名/swagger-ui.html
升级版访问路径：项目端口:服务名/doc.html
下面是原生效果图。升级版效果图放在了文章开始的位置。