swagger 超简单入门教程使用（自测）

网上swagger 的资料比较多，用到时还是遇到不少坑的，所以自己进行一下整理自己的学习过程

1.安装，集成到springboot
方式一 纯注解式
方式二 引用jar 自配

swagger编写规范

环境:
1,jdk1.8
2,idea
3,spring-boot-starter-parent版本1.5.6.RELEASE
4,springfox-swagger2.7.0 And springfox-swagger-ui 版本2.7.0。如果修改版本号后持续报错，尝试删除.m2目录里面swagger的所有jar包，

1 Swagger环境搭建

新建一个工程，file->new->Porject->Spring Initializr->next-（idea专业版本，社区版可以到git上复制pom文件）

pom.xml文件中添加如下内容(看清楚再复制，此处不是全部内容)

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

2.Swagger编写sample

在config目录中新建swagger的配置文件swaggerConfig.java

@Configuration
@EnableSwagger2
@ComponentScan(basePackages = {"myj.controller"})
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        List<Parameter> pars = new ArrayList<>();
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.withClassAnnotation(RestController.class))
                .paths(PathSelectors.any())
                .build()
                .globalOperationParameters(pars)
                .apiInfo(apiInfo());
    }

    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("exam RESTful Web Service APIs")
                .description("exam")
                .termsOfServiceUrl("http://localhost:8081")
                .version("1.0")
                .build();
    }
}

新建实体类User，基本字段如下

public class User {

    //在swagger-ui.html#页面中如果返回User，ModelModel Schema选项卡可见，包括如入参和出参
    @ApiModelProperty(value = "用户的姓名，比如'李四'")
    private String name;
    @ApiModelProperty(value = "id",required = true)
    private String id;
    @ApiModelProperty(value = "用户的年龄，比如：20")
    private Integer age;

    ....省略set和get方法，
}

在controller包立新建TestController，内容如下

@Api(value = "User-API",description = "这是用户接口详细信息的描述")
@RestController
@RequestMapping("/test")
public class TestController {

    static Map<String, User> users = Collections.synchronizedMap(new HashMap<String, User>());


    @ApiOperation(value = "获取用户列表", notes = "根据url的id来获取用户详细信息，返回List<User>类型用户信息的JSON")
    @RequestMapping(value = {""}, method = RequestMethod.GET,produces = "application/json;charset=UTF-8")
    public List<User> getUserList() {
        List<User> r = new ArrayList<User>(users.values());
        return r;
    }

    ....省略n行代码
}

3 注释图片简析

5 注释常用属性解释

@Api 标记一个Controller类做为swagger文档资源，以及该Controller的描述

@Api(value = “User-API”,description = “这是用户接口详细信息的描述”)

属性名称	备注
value	url的路径值
description	对api资源的详细描述

@ApiOperation每一个url资源的说明

@ApiOperation(value = “获取用户列表”,notes = “根据url的id来获取用户详细信息，返回List类型的JSON用户信息”)

属性名称	备注
value	接口操作简介
notes	接口描述

@ApiImplicitParam对容器的描述 
@ApiImplicitParam(name = “user”, value = “用户详细实体user”, required = true, dataType = “User”)

属性名称	备注
name	属性名称
value	属性介绍
required	是否属性必填
dataType	数据类型(int,string, 或者自定义实体类)
paramType	参数类型

@ApiModelProperty对model中某字段属性的描述 
@ApiModelProperty(value = “id”,required = true)

属性名称	备注
value	属性名称
required	属性是否必填

6 文档编写规范建议

·model的描述

@ApiModelProperty(value = “用户姓名”,required = true)
private String name;
对字段的描述

value：实体类中字段的描述以及可选的取值。例如sex表示用户性别1:男，0:女 
required：该字段是否必填，不清楚情况下，建议不要填写，或者required=false

controller的描述
@Api(value = “User-API”, description = “用户接口详情”)
对controler的描述

value:如果controller类名为UserController，那么此处该名称叫User-API。 
description：接口详细描述，建议不要超过25个字。

@ApiOperation(value = “获取用户详细信息”, notes = “根据url的id来获取用户详细信息，返回User类型用户信息的实体”)
对该方法的描述

value:接口操作简介，建议不超过15个字。 
notes：1，输出结果代表的意义，2实现的功能。若输出结果为基本类型（类似：int,string）需要指名是什么类型，如果有异常信息，需要指明异常信息的类型。

@ApiImplicitParam(name = “id”, value = “用户ID”, required = true, dataType = “String”)
对参数的描述，如果多个参数需要用@ApiImplicitParams对其进行包裹

name:跟方法名中的参数保持一致。 
value：对参数的简单描述，说明该参数的意义。 
required:该参数是否必填写。 
dataType:入参的类型，可以为类名，也可以为基本类型（String，int，Boolean），加包名，如果都不是则不翻译 
paramType：如果在路径中提取参数用path，比如:在／A／{XXX}路径中得到XXX的值，候选址参数query, body,header。

7 修改从maven下载的jar包
有些jar包，比如swagger-ui包中html的显示，满足不了现有系统的要求，可以根据需求直接修改从maven下载的jar包。（修改内容略过）
1，解压文件

1.unzip springfox-swagger-ui-2.7.0.jar  -d temp

2，进入临时目录temp,编辑文件
3，压缩已经修改的文件

jar cvfm0 springfox-swagger-ui-2.7.0.jar META-INF/MANIFEST.MF

4，重命名源文件

mv springfox-swagger-ui-2.7.0.jar springfox-swagger-ui-2.7.0.jar.old

5,移动修改过后的文件

cp springfox-swagger-ui-2.7.0.jar ../