Swagger入门

参考:

https://www.cnblogs.com/JoiT/p/6378086.html

Swagger组成

Swagger spec：这一块对元素的嵌套、命令等采用官方模式。如果你想要对 Swagger 文件手动编码，你必须非常熟悉 Swagger spec。
Swagger editor：这是在线编辑器，用于验证你的 YML 格式的内容是否违反 Swagger spec 。YML 是一种句法，依赖于空格和嵌套。

Swagger-UI：这是一套 HTML/CSS/JS 框架用于解析遵守 Swagger spec 的 JSON 或 YML 文件，并且生成API文档的UI导航。
Swagger-codegen：这个工具可以为不同的平台生成客户端 SDK（比如 Java、JavaScript、Python 等）。这些客户端代码帮助开发者在一个规范平台中整合 API ，并且提供了更多健壮的实现，可能包含了多尺度、线程，和其他重要的代码。SDK 是用于支持开发者使用 REST API 的工具。

静态Swagger, 由配置文件生成接口描述

1. 创建一个Swagger Spec文件

http://editor.swagger.io/#/

2. 在editor中编辑一个spac文件

3. 编辑完成后下载swagger.yaml到本地

4. 下载swaggerUI

https://github.com/swagger-api/swagger-ui

只需要Dist目录,并将其部署到html服务器上

5. 打开"dist/index.html"

找的url = "..../swagger.json"

修改为url = "swagger.yaml" ,并将swagger.yaml文件放入dist目录中.

6. 将dist目录上传到html服务器,供大家使用

如:http://localhost:8080/static/api/index.html

动态Swagger,配置由java注解\注释生成

1. 添加swagger包的maven依赖

在项目跟目录下pox.xml中

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

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

2. 添加配置文件,

在spring-mvc.xml中,添加一个bean.

    <!--&lt;!&ndash; swagger 配置&ndash;&gt;-->
    <bean name="applicationSwaggerConfig" class="com.okoxy.apidoc.MySwaggerConfig"/>

3. 加入swagger自动配置文件

类:

com.okoxy.apidoc.MySwaggerConfig

@EnableWebMvc
@EnableSwagger2
@Configuration
public class MySwaggerConfig{
    @Bean
    public Docket createRestApi() {
        return new Docket(DocumentationType.SWAGGER_2)
                .apiInfo(apiInfo())
                .select()
                .apis(RequestHandlerSelectors.any())
                .paths(PathSelectors.any())
                .build();
    }
    private ApiInfo apiInfo() {
        return new ApiInfoBuilder()
                .title("Spring 中使用Swagger2构建RESTful APIs")
                .termsOfServiceUrl("http://localhost:8080/v2/api-docs")
                .contact("zuolifeng@sina.com")
                .version("1.1")
                .build();
    }
}

Spring整合swagger是使用springfox做的.文档见

Docs: http://springfox.github.io/springfox/docs/current/

项目地址: https://springfox.github.io/springfox/