简介

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务,可以和Spring很好的结合。
Swagger是个比较大的项目,本文主要介绍如何与SpringMVC结合生成RESTful风格的文档.

环境

spring 的版本是 4.0.2.RELEASE
swagger 用的是1
swagger-ui 版本 2.2.10

Maven

 <dependency>
            <groupId>com.mangofactory</groupId>
            <artifactId>swagger-springmvc</artifactId>
            <version>1.0.2</version>
        </dependency>

        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-annotations</artifactId>
            <version>${version.jackson}</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>${version.jackson}</version>
        </dependency>
        <dependency>
            <groupId>com.fasterxml.jackson.core</groupId>
            <artifactId>jackson-core</artifactId>
            <version>${version.jackson}</version>
        </dependency>
     <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <version.jackson>2.4.4</version.jackson>
    </properties>

Swagger 配置

本文使用的swagger1
swagger2配置使用的是Springfox,请参考另外教程
在项目中用java写一个配置文件

@Configuration
@EnableSwagger
@EnableWebMvc
@ComponentScan("[扫描接口]")
public class MySwaggerConfig {

    private SpringSwaggerConfig springSwaggerConfig;

    /**
     * Required to autowire SpringSwaggerConfig
     */
    @Autowired
    public void setSpringSwaggerConfig(SpringSwaggerConfig springSwaggerConfig)
    {
        this.springSwaggerConfig = springSwaggerConfig;
    }

    /**
     * Every SwaggerSpringMvcPlugin bean is picked up by the swagger-mvc
     * framework - allowing for multiple swagger groups i.e. same code base
     * multiple swagger resource listings.
     */
    @Bean
    public SwaggerSpringMvcPlugin customImplementation()
    {
        return new SwaggerSpringMvcPlugin(this.springSwaggerConfig)
                .apiInfo(apiInfo())
                .includePatterns(".*?");
    }

    private ApiInfo apiInfo()
    {
        ApiInfo apiInfo = new ApiInfo(
                "My Apps API Title",
                "My Apps API Description",
                "My Apps API terms of service",
                "My Apps API Contact Email",
                "My Apps API Licence Type",
                "My Apps API License URL");
        return apiInfo;
    }
}

然后在Spring配置文件中声明

    <!--正式发布时注释掉-->
    <bean class="com.keqiang.swagger.MySwaggerConfig"/>

接下来下载 Swagger-ui 把dist文件中的所有东西拷贝到web根目录下(放在其他的放也是可以的,只要能访问的到)

修改index.html文件中的路径：
默认是从连接http://petstore.swagger.io/v2/swagger.json获取API的JSON,我们改为 http://{ip}:{port}/{projectName}/api-docs 的形式，也就ip:端口号/项目名/api-docs

注解参数

不是十分详细 可以参考下面的网站
swagger常用注解说明

• Api
• ApiModel
• ApiModelProperty
• ApiOperation
• ApiParam
• ApiResponse
• ApiResponses
• ResponseHeader

• @API：表示一个开放的API，可以通过description简明的描述API的功能，produce指定API的mime类型
• 一个@API下，可以有多个@ApiOperation,表示针对该API的CRUD操作，在ApiOperation Annotation中还可以通过value，notes描述该操作的作用，response描述正常情况下该请求返回的对象类型
• 在一个@ApiOperation下，可以通过@ApiResponses描述API操作可能出现的异常情况
• @ApiParam用于描述该API操作接收的参数类型，value用于描述参数，required指明参数是否为必须。
• @ApiModelProperty中，value指定描述，required指明是否为必须

参考网址

Swagger 官网
Swagger-ui
Swagger 简介
Swagger 博客
基于swagger的RESTful API开发实践
如何编写基于OpenAPI规范的API文档
API文档工具-Swagger的集成