swagger编写规范

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文件中添加如下内容(看清楚再复制，此处不是全部内容)

    <properties>
        ...
        <swagger.version>2.7.0</swagger.version>
        ...
    </properties>

        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger2</artifactId>
            <version>${swagger.version}</version>
        </dependency>
        <dependency>
            <groupId>io.springfox</groupId>
            <artifactId>springfox-swagger-ui</artifactId>
            <version>${swagger.version}</version>
        </dependency>

2 Swagger编写sample

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

@EnableSwagger2
@Configuration
public class SwaggerConfig {

    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.basePackage("com"))//扫描com路径下的api文档
                .paths(PathSelectors.any())//路径判断
                .build();
    }

    private ApiInfo apiInfo() {
      return new ApiInfoBuilder()
                .title("Swagger 开发规范")//标题
                .description("Saggger 开发规范详文档细地址--->>>>>>>：http://www.google.com.hk")//描述
                .termsOfServiceUrl("http://www.google.com.hk")//（不可见）条款地址
                .version("6.6.6")//版本号
                .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 注释图片简析

浏览该地址，访问主页面：http://localhost:8080/swagger-ui.html#
浏览该地址，访问sagger专有JsonAPI： http://localhost:8080/v2/api-docs

4 Swagger try it out！功能

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，解压文件

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 ../

附上项目地址

https://github.com/zhaozhen/swagger