【总结】swagger

1.swagger概念及配置

1.1基本概念

1、是一款让你更好的书写API文档的规范且完整框架。

2、提供描述、生产、消费和可视化RESTful Web Service。

3、是由庞大工具集合支撑的形式化规范。这个集合涵盖了从终端用户接口、底层代码库到商业API管理的方方面面

1.2使用方式

1. 方式一：使用springboot提供的第三方依赖

	<dependency>
		<groupId>com.spring4all</groupId>
		<artifactId>swagger-spring-boot-starter</artifactId>
		<version>1.7.0.RELEASE</version>
	</dependency>

1. 方式二：使用官方依赖

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

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

1. Swagger的configuration

@Configuration
@EnableSwagger2
public class Swagger2 {

        @Bean
        public Docket createRestApi() {
            return new Docket(DocumentationType.SWAGGER_2)
                    .apiInfo(apiInfo())
                    .select()
                    .apis(RequestHandlerSelectors.basePackage("com.yss.ms.admin"))
                    .paths(PathSelectors.any())
                    .build();
        }

        private ApiInfo apiInfo() {
            return new ApiInfoBuilder()
                    .title("服务:发布为daocke镜像,权限管理，用户管理，页面管理，日志 后台 APIs")
                    .description("服务:发布为daocke镜像,权限管理，用户管理，页面管理，日志 后台")
                    .termsOfServiceUrl("http://192.168.1.198:10070/platformgroup/ms-admin")
                    .contact("程序猿")
                    .version("1.0")
                    .build();
        }

    }

2.swagger具体使用

2.1swagger常用注解

（1）@Api()用于类：表示标识这个类是swagger的资源

（2）@ApiOperation()：用于方法：表示一个http请求的操作

（3）@ApiParam()：用于方法，参数，字段说明：表示对参数的添加元数据（说明或是否必填等）

public BindOffLineFrameResponse bindOffLineFrame(@ApiParam("UserId") @RequestParam("UserId") int UserId,){}

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

（5）@ApiModelProperty()：用于字段表示对model属性的说明