Swagger完全教程

Swagger定义及为何使用

定义

Swagger 是一个规范和完整的框架，用于生成、描述、调用和可视化 RESTful 风格的 Web 服务

目标

总体目标是使客户端和文件系统作为服务器以同样的速度来更新。
文件的方法，参数和模型紧密集成到服务器端的代码，允许API来始终保持同步。 Swagger 让部署管理和使用功能强大的API从未如此简单。

好处

• Swagger 可以生成一个具有互动性的API控制台，开发者可以用来快速学习和尝试API。

• Swagger 可以生成客户端SDK代码用于各种不同的平台上的实现。

• Swagger 文件可以在许多不同的平台上从代码注释中自动生成。

• Swagger 有一个强大的社区，里面有许多强悍的贡献者。

Swagger与Easy Mock

Easy Mock作用

主要为前端测试提供模拟数据，更好地帮助前后端分离，同步开发，也可用于微服务间调用的模拟数据

Swagger 与 Easy Mock的对接

1. 将生成的swagger.json上传至 Easy Mock 服务
2. 在Easy Mock上配置同步的swagger地址

Swagger 与 Restful

Restful规范

1. 请求方式代表动词，为以下五种
   • GET：读取（Read）
   • POST：新建（Create）
   • PUT：更新（Update）
   • PATCH：更新（Update），通常是部分更新
   • DELETE：删除（Delete）
2. URL 代表宾语，且需要是名词，操作是集合时，需要是复数
3. 请求和相应参数都为JSON对象，故HTTP头的Content-Type属性应为application/json
4. 状态码需要精确
5. 提供服务链接

参考：http://www.ruanyifeng.com/blog/2018/10/restful-api-best-practices.html

Swagger Tools

1. Swagger UI： 一个无依赖的HTML、JS和CSS集合，可以为Swagger兼容API动态生成优雅文档。
2. Swagger Editor： 可浏览编辑swagger.json显示的API接口
3. Swagger Generators: 可以生成客户端SDK代码用于各种不同的平台上的实现

Swagger.json

swagger.json相当于跨工具API接口的序列化数据

Java生成Swagger.json、html和pdf

1. 引入swagger的maven包

        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-swagger2artifactId>
            <version>2.9.2version>
            <scope>providedscope>
        dependency>
        <dependency>
            <groupId>io.springfoxgroupId>
            <artifactId>springfox-swagger-uiartifactId>
            <version>2.9.2version>
            <scope>providedscope>
        dependency>
        <dependency>
            <groupId>io.swaggergroupId>
            <artifactId>swagger-modelsartifactId>
            <version>1.5.20version>
        dependency>

2. 在接口和参数和返回值上加入swagger注解

@Api(value = "/api/item", description = "条目", tags = {"[条目]"})
@RestController
public class SwaggerController {

    @Autowired
    private ItemService itemService;

    @ApiOperation(value = "查询条目", notes = "调用方：", produces = MimeTypeUtils.APPLICATION_JSON_VALUE, httpMethod = "POST")
    @ApiImplicitParams({
            @ApiImplicitParam(value = "标签", name = "id", required = true, paramType = "query", dataType = "string")})
    @RequestMapping(value = "/items/{id}",method = RequestMethod.GET)
    @ResponseBody
    public Item getItems(@PathVariable("id") Long id){
        return itemService.queryItem(id);
    }

}

@Data
@NoArgsConstructor
@AllArgsConstructor
@ApiModel(description = "条目详细信息")
public class Item {
    @ApiModelProperty(value = "条目ID")
    private Long id;
    @ApiModelProperty(value = "条目标题")
    private String title;
    @ApiModelProperty(value = "条目图片URL")
    private String pic;
    @ApiModelProperty(value = "条目描述")
    private String desc;
    @ApiModelProperty(value = "条目价格")
    private Long price;
}

3. 通过maven-surefire-plugin插件执行单元测试输出swagger.json

@RunWith(SpringJUnit4ClassRunner.class)
@WebAppConfiguration
@ContextConfiguration(locations = {"classpath:spring-mvc.xml"})
public class Swagger2MackupTest {

    @Autowired
    private WebApplicationContext webApplicationContext;

    private MockMvc mockMvc;

    @Before
    public void init(){
        this.mockMvc = MockMvcBuilders.webAppContextSetup(this.webApplicationContext).build();
    }

    @Test
    public void getJson() throws Exception {
        String outputDir = "target/swagger";
        MvcResult mvcResult = this.mockMvc.perform(get("/v2/api-docs").accept(MediaType.APPLICATION_JSON)).andExpect(status().isOk()).andReturn();
        String json = mvcResult.getResponse().getContentAsString();
        File outputFile = Paths.get(outputDir).toFile();
        if (!outputFile.exists()){
            outputFile.mkdirs();
        }
        FileUtils.writeStringToFile(new File(outputFile,"swagger.json"),json, StandardCharsets.UTF_8);
    }
}

                <plugin>
                    <groupId>org.apache.maven.pluginsgroupId>
                    <artifactId>maven-surefire-pluginartifactId>
                    <configuration>
                        <includes>
                            <include>**/Swagger2MarkupTest.javainclude>
                        includes>
                    configuration>
                plugin>

4. 通过swagger2markup-maven-plugin插件，将swagger.json转化为asciidoc

 
  <properties>
        <asciidoctor.input.directory>${project.basedir}/src/docs/jsonasciidoctor.input.directory>
        <swagger2markup.version>1.2.0swagger2markup.version>
        <asciidoctor.input.directory>${project.basedir}/src/docs/asciidocasciidoctor.input.directory>

        <swagger.output.dir>${project.build.directory}/swaggerswagger.output.dir>
        <swagger.snippetOutput.dir>${project.build.directory}/asciidoc/snippetsswagger.snippetOutput.dir>
        <generated.asciidoc.directory>${project.build.directory}/asciidoc/generatedgenerated.asciidoc.directory>
        <asciidoctor.html.output.directory>${project.build.directory}/asciidoc/htmlasciidoctor.html.output.directory>
        <asciidoctor.pdf.output.directory>${project.build.directory}/asciidoc/pdfasciidoctor.pdf.output.directory>

        <swagger.input>${swagger.output.dir}/swagger.jsonswagger.input>
    properties>

 
            <plugin>
                <groupId>io.github.swagger2markupgroupId>
                <artifactId>swagger2markup-maven-pluginartifactId>
                <version>${swagger2markup.version}version>
                <dependencies>
                    <dependency>
                        <groupId>io.github.swagger2markupgroupId>
                        <artifactId>swagger2markup-import-files-extartifactId>
                        <version>${swagger2markup.version}version>
                    dependency>
                    <dependency>
                        <groupId>io.github.swagger2markupgroupId>
                        <artifactId>swagger2markupartifactId>
                        <version>${swagger2markup.version}version>
                    dependency>
                dependencies>
                <configuration>
                    
                    <swaggerInput>${swagger.input}swaggerInput>
                    <outputDir>${generated.asciidoc.directory}outputDir>
                    <config>
                        
                        <swagger2markup.markupLanguage>ASCIIDOCswagger2markup.markupLanguage>
                        
                        <swagger2markup.pathsGroupedBy>TAGSswagger2markup.pathsGroupedBy>
                        
                        
                    config>
                configuration>
                <executions>
                    <execution>
                        <phase>generate-sourcesphase>
                        <goals>
                            <goal>convertSwagger2markupgoal>
                        goals>
                    execution>
                executions>
            plugin>

5. 从asciidoc2html-demo获取 src/docs/asciidoc下编写的index.adoc,可引入自定义的adoc文件（若不引入自定义文件，可从target获取adoc文件）

	include::{generated}/overview.adoc[]
	include::starting.adoc[]
	include::{generated}/paths.adoc[]
	include::{generated}/security.adoc[]
	include::ending.adoc[]
	include::{generated}/definitions.adoc[]

6. 通过asciidoctor-maven-plugin将asciidoc转换为html/pdf

  <plugin>
                <groupId>org.apache.maven.pluginsgroupId>
                <artifactId>maven-compiler-pluginartifactId>
                <version>3.6.1version>
                <configuration>
                    <source>1.8source>
                    <target>1.8target>
                    <encoding>UTF-8encoding>
                configuration>
            plugin>
            
            <plugin>
                <groupId>org.asciidoctorgroupId>
                <artifactId>asciidoctor-maven-pluginartifactId>
                <version>1.5.3version>
                
                <dependencies>
                    <dependency>
                        <groupId>org.asciidoctorgroupId>
                        <artifactId>asciidoctorj-pdfartifactId>
                        <version>1.5.0-alpha.10.1version>
                    dependency>
                    
                    <dependency>
                        <groupId>org.jrubygroupId>
                        <artifactId>jruby-completeartifactId>
                        <version>1.7.21version>
                    dependency>
                dependencies>
                
                <configuration>
                    
                    <sourceDirectory>${asciidoctor.input.directory}sourceDirectory>
                    
                    
                    <attributes>
                        <doctype>bookdoctype>
                        <toc>lefttoc>
                        <toclevels>3toclevels>
                        <numbered>numbered>
                        <hardbreaks>hardbreaks>
                        <sectlinks>sectlinks>
                        <sectanchors>sectanchors>
                        <generated>${generated.asciidoc.directory}generated>
                    attributes>
                configuration>
                
                <executions>
                    <execution>
                        <id>output-htmlid>
                        <phase>generate-resourcesphase>
                        <goals>
                            <goal>process-asciidocgoal>
                        goals>
                        <configuration>
                            <backend>html5backend>
                            <outputDirectory>${asciidoctor.html.output.directory}outputDirectory>
                        configuration>
                    execution>

                    
                    <execution>
                        <id>output-pdfid>
                        <phase>generate-resourcesphase>
                        <goals>
                            <goal>process-asciidocgoal>
                        goals>
                        <configuration>
                            <backend>pdfbackend>
                            <outputDirectory>${asciidoctor.pdf.output.directory}outputDirectory>
                        configuration>
                    execution>
                executions>
            plugin>

Refrences

1. maven-surefire-plugin
2. asciidoctor-maven-plugin
3. 通过swagger2markup+asciidoctorj生成html和pdf文档并解决asciidoctorj生成的pdf文件中文显示不全问题
4. 微服务之Swagger