Swagger 接口配置

一：swagger是什么？

1、是一款让你更好的书写API文档的规范且完整框架。
2、提供描述、生产、消费和可视化RESTful Web Service。
3、是由庞大工具集合支撑的形式化规范。这个集合涵盖了从终端用户接口、底层代码库到商业API管理的方方面面。

二 :Swagger接口生成工作原理

1、系统启动，扫描到api工程中的Swagger2Configuration类
2、在此类中指定了包路径com.xuecheng，找到在此包下及子包下标记有@RestController注解的controller类
3、根据controller类中的Swagger注解生成接口文档。

三:如何使用

1、在pom.xml文件中添加swagger相关依赖

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

第一个是API获取的包，第二是官方给出的一个ui界面。这个界面可以自定义，默认是官方的，对于安全问题，以及ui路由设置需要着重思考。

/**
 * @description: swagger2配置文件类
 * @访问路径： 如 http://localhost:8080/swagger-ui.html
 **/
@Configuration
public class Swagger2Config {
    private String basePackage = "com.asiainfo.crm.engine.controller";


    @Bean
    public Docket createRestApi() {
        List<Parameter> pars = new ArrayList<Parameter>();
        ParameterBuilder appId = new ParameterBuilder();
        //自定义参数
        appId.name("X-APP-ID").description("X-APP-ID")
                .modelRef(new ModelRef("String")).parameterType("header")
                .defaultValue("FFnN2hso42Wego3pWq4X5qlu")
                .required(true).build(); //header中的ticket参数非必填，传空也可以
        pars.add(appId.build());    //根据每个方法名也知道当前方法在设置什么参数

       

       
      

        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .groupName("中心组合服务")
                .genericModelSubstitutes(DeferredResult.class)
                .useDefaultResponseMessages(false)
                .forCodeGeneration(true)
                .select()
                .apis(RequestHandlerSelectors.basePackage(basePackage))
                .apis(RequestHandlerSelectors.withMethodAnnotation(ApiOperation.class))
                .paths(PathSelectors.any())
                .build().globalOperationParameters(pars);

    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("我的文档")
                .description("")
                .version("1.0")
                .license("")
                .licenseUrl("http://www.limeng6868.com/")
                .build();
    }


}

在Java类中添加Swagger的注解即可生成Swagger接口，常用Swagger注解如下：
@Api：修饰整个类，描述Controller的作用 @ApiOperation：描述一个类的一个方法，或者说一个接口
@ApiParam：单个参数描述 @ApiModel：用对象来接收参数 @ApiModelProperty：用对象接收参数时，描述对
象的一个字段 @ApiResponse：HTTP响应其中1个描述 @ApiResponses：HTTP响应整体描述 @ApiIgnore：使用
该注解忽略这个API @ApiError ：发生错误返回的信息 @ApiImplicitParam：一个请求参数
@ApiImplicitParams：多个请求参数

盗张图 嘿嘿:

@Api(value="管理接口",description = "c管理接口，增、删、改、查")
public interface CmsPageControllerApi {
@ApiOperation("分页查询页面列表")
@ApiImplicitParams({
@ApiImplicitParam(name="page",value = "页
码",required=true,paramType="path",dataType="int"),
@ApiImplicitParam(name="size",value = "每页记录
数",required=true,paramType="path",dataType="int")
})
public QueryResponseResult findList(int page, int size, QueryPageRequest queryPageRequest) ;
}