I am trying to write a little Api using Slim. I want to have it documented very well so I installed swagger-php and UI and investigated on it the last days. For some reason my petstore demo is missing all the post annotations. My API will look like in this example:
http://coenraets.org/blog/2011/12/restful-services-with-jquery-php-and-the-slim-framework/
How would the swagger annotations for the addWine() function look like?
How do I annotate the result of the function (last insert id), since it is no model ?
An example would be really great.
Thank you
This would do it. Propably not ment to be like this, but doing exactly what I wanted.
/**
* #package
* #category
* #subpackage
*
* #SWG\Resource(
* apiVersion="1.0.0",
* swaggerVersion="1.2",
* basePath="http://myapi",
* resourcePath="/hello",
* description="Giving you your name in case you forgot it",
* produces="['application/json','application/xml','text/plain','text/html']"
* )
*/
/**
* #SWG\Api(
* path="/hello/{yourname}",
* #SWG\Operation(
* method="GET",
* summary="Gives you your name",
* notes="Returns your name",
* type="hello",
* nickname="yourname",
* #SWG\Parameter(
* name="yourname",
* description="Enter your name",
* required=true,
* type="text",
* paramType="path"
* ),
* #SWG\ResponseMessage(code=404, message="Bad, really bad name.")
* )
* )
*
*/
/**
* #package
* #category
* #subpackage
*
* #SWG\Model(id="hello",required="name")
*/
/**
* #SWG\Property(name="name",type="string",description="Your name")
*/
Related
I have my custom operation for an entity, it uses PUT method, i ould like to document the parameter in my swagger (OpenApi) documentation.
This is the definition
/*
* itemOperations={
* "get",
* "patch",
* "put",
* "delete",
* "activate"={
* "method"="PUT",
* "path"="/user/{token}/activate",
* "requirements"={"token"="^\w{32}$"},
* "controller"=ActivateUser::class,
* "normalization_context"={"groups"={"user:read"}},
* "denormalization_context"={"groups"={"user:activation"}},
* "read"=false,
* "validation_groups"={"Activate"},
* "openapi_context"={
* "summary"="Attiva un utente tramite token dopo la registrazione.",
* "description"="Cambia lo stato dell'utente in 'attivo' permettendo così il login.",
* "parameters"={
* {
* "in"="path",
* "name"="token",
* "required"=true,
* "type"="string",
* "description"="Il token generato al momento della registrazione."
* }
* }
* }
* },
* },
*/
The part interested is the "openapi_context" key then "parameters".
This description doesn't change anything about parameters definitions, the ID requirement still remains and there's no token description (i read the documentation here for path parameters in open api context
Where am i wrong? Is there a way to do it?
I need to implement this function:
// TODO Capitalize the users username, firstName and lastName
// using #asyncCapitalizeUser method below
Flux<User> asyncCapitalizeMany(Flux<User> flux) {
}
Mono<User> asyncCapitalizeUser(User u) {
return Mono.just(
new User(u.getUsername().toUpperCase(),
u.getFirstname().toUpperCase(),
u.getLastname().toUpperCase()));
}
My implementation:
return flux
.map(user -> asyncCapitalizeUser(user))
.flatMap(Mono::flux)
Is this correct, and can it be improved?
Just this is enough:
return flux
.flatMap(this::asyncCapitalizeUser);
/**
* Transform the elements emitted by this {#link Flux} asynchronously into Publishers,
* then flatten these inner publishers into a single {#link Flux} through merging,
* which allow them to interleave.
* <p>
* There are three dimensions to this operator that can be compared with
* {#link #flatMapSequential(Function) flatMapSequential} and {#link #concatMap(Function) concatMap}:
* <ul>
* <li><b>Generation of inners and subscription</b>: this operator is eagerly
* subscribing to its inners.</li>
* <li><b>Ordering of the flattened values</b>: this operator does not necessarily preserve
* original ordering, as inner element are flattened as they arrive.</li>
* <li><b>Interleaving</b>: this operator lets values from different inners interleave
* (similar to merging the inner sequences).</li>
* </ul>
* <p>
* <img class="marble" src="https://raw.githubusercontent.com/reactor/reactor-core/v3.1.0.M3/src/docs/marble/flatmap.png" alt="">
* <p>
* #param mapper the {#link Function} to transform input sequence into N sequences {#link Publisher}
* #param <R> the merged output sequence type
*
* #return a new {#link Flux}
*/
public final <R> Flux<R> flatMap(Function<? super T, ? extends Publisher<? extends R>> mapper) {
I am trying to write a disassembler for Mindstorms EV3 VM binaries, preferably in Python, since I am very familiar with it. I have docs detailing the instructions set, opcodes, parameters, data types etc. which is available here but I am having trouble building an actual disassembler from that.
As I understand it, writing a disassembler is not much different from writing a compiler in that it's just a glorified deterministic finite-State machine. However, beyond that, I can not find any books or guides on writing one. I attempted to use compiler writing tools such as Lex and Yacc (or in python PLY), however all of those tools fail me in some way.
The Lex and Yacc combo does not appear to be something I can use because it does the reverse of what I want to do. It generates tokens from text, which you then turn into bytecode, whereas I have bytecode and want to turn it into tokens, which I then turn into text. As I see it the only option I have is writing my own parser generator, which I would like to avoid as it seems like a lot of work.
Another issue I have is that I do not know how to deal with things like null-terminated strings and the parameter encoding (some arguments are prefixed by a byte with certain bits set telling the VM what length and type to expect, which I presume means I can not parse the whole bytecode with a simple DFA at a byte level)
How would I write a disassembler for a format like this?
Writing binary disassemblers really mean you want to specify patterns of binary data, and relationships between decode entities (if you recognize two instructions, it is reasonable to assume they don't overlap).
Conventional parsers don't do this very well (although you can certainly write a grammar for a sequence of instructions assuming individual bits or bytes as tokens; you'll still have to handle gaps between instuction sequences).
The smartest approach I've seen for this is a tool called SLED by Norman Ramsey and his team, which lets you write succinct patterns for binary data, and assembles it into binary encoders and decoders automatically. This research paper discusses SLED and a number of similar systems. A key point: these are much more than a "parser generator" but the concept is similar: many patterns to describe the data, a code generator to assemble the patterns into an efficient engine to match them all.
To give you a flavor of what these tools look like, I offer a fragment of a partial x86-64 encoding based on some work I have done in this area. The idea is to define named patterns (with constraints) that compose so that you can eventually write an instruction definition. Here's a brief sample of a small part (the whole thing is some 1200 lines):
datatype SIB
{ ScaleSize: unsigned encoding { Times1=0 Times2=1 Times4=2 Times8=3} 2 bits
ScaledIndex: unsigned encoding { EAX=0 ECX=1 EDX=2 EBX=3 none=4 EBP=5 ESI=6 EDI=7 } 3 bits
IndexRegister: unsigned encoding { EAX=0 ECX=1 EDX=2 EBX=3 ESP=4 EBP,disp32=5 ESI=6 EDI=7 } 3 bits
}
encoding Grp1 { ADD=0 OR ADC SBB AND SUB XOR CMP }
encoding Grp1A { POP=0 * * * * * * * }
encoding Grp2 { ROL=0 ROR RCL RCR SHL,SAL SHR * SAR }
encoding Grp3 { TESTIbIz=0 * NOT NEG MULAX,MULrAX IMULAL,IMULrAX DIVAL,DIVrAX IDIVAL,IDIVrAX }
encoding Grp4 { INCEb=0 DECEb * * * * * * }
encoding Grp5 { INCEv=0 DECEv CALLNEv CALLFEp JMPNEv JMPFEp PUSHEv * }
encoding Grp6 { SLDTRvMW=0 STRRvMw LLDTEw LTREw VERREw VERWEw * * }
encoding Grp7mem { SGDTMs=0 SIDTMs LGDTMs LIDTMs SMSWMwRv * LMSWEw INVLPGMb }
encoding Grp7reg { VMCALL,VMLAUNCH,VMRESUME,VMXOFF=0 MONITOR,MWAIT * * SMSWMwRv * LMSWEw SWAPGS }
encoding Grp8 { *=0 * * * BT BTS BTR BTC }
encoding Grp9mem { * CMPXCH8BMq,CMPXCH16BMdq * * * * VMPTRLDMq,VMCLEARMq,VMXONMq VMPTRSTMq }
encoding Grp9reg { *=0 * * * * * * * }
encoding Grp10 { * * * * * * * }
encoding Grp11Ib { MOVEbIb * * * * * * * }
encoding Grp11Iz { MOVEvIz * * * * * * * }
encoding Grp12mem { * * * * * * * * }
encoding Grp12reg { *=0 * * PSRLWNqIb,PSRLWUdqIb * PSRAWNqIb,PSRAWUdqIb * PSLLWNqIb,PSLLWUdqIb * }
encoding Grp13mem { * * * * * * * * }
encoding Grp13reg { *=0 * * PSRLDNqIb,PSLRDUdqIb * PSRADNqIb,PSRADUdqIb * PSLLDNqIb,PSLLDUdqIb * }
encoding Grp14mem { * * * * * * * * }
encoding Grp14reg { *=0 * * PSRLQNqIb,PSRLQUdqIb PSRLDQUdqIb * * PSLLQNqIb,PSLLQUdqIb PSLLDQUDqIb }
encoding Grp15mem { FXSAVE=0 FXRSTOR LDMXCSR STMXCSR * * * CFLUSH }
encoding Grp15reg { *=0 * * * LFENCE MFENCE SFENCE }
encoding Grp16mem { PREFETCHNTA=0 PREFETCHT0 PREFETCHT1 PREFETCHT2 * * * }
encoding Grp16reg { * * * * * * * * }
...
instruction { ADCr64Immediate => Grp1.ADC
ADDr64Immediate => Grp1.ADD
ANDr64Immediate => Grp1.AND
CMPr64Immediate => Grp1.CMP
ORr64Immediate => Grp1.OR
SBBr64Immediate => Grp1.SBB
SUBr64Immediate => Grp1.SUB
XORr64Immediate => Grp1.XOR
}
(Target: Register32, Immediate: signed 32 bits)
BasicInstruction
& prefix_length0
& if Intel64 => prefix_REX(W=On R=Target:3)
& OneByteOpcode & Subcode=ImmGrp1EvIz
& ModRM(Mod=reg RSlashM=Target:2-0 reg=*)
If you are really decoding just a simple virtual machine with a simple instruction set, maybe you don't need all this capability, because a "simple VM" doesn't pack bits or split data across byte boundaries, and/or you can hack your way through the few cases that violate these assumptions. As people's VMs get more complex (they evolve over years), they necessarily get more complicated. YMMV.
I am concerned on generating Model/Example value section for my GET request with Swagger.
The link to official example shows that section perfectly.
In official docs it is generated using existing model:
* #SWG\Schema(ref="#/definitions/User")
I don't have such an option, because my properties is generated by REST.
I have tried the following way:
/**
* #SWG\Get(
...
* #SWG\Response(
* response="200",
* description="Ok",
* #SWG\Schema(
* type="array",
* #SWG\Property(property="firstname", type="string", example="Steven")
* ),
* ),
* )
*/
It is not working and answers:
fetching resource list: http://localhost/dist/swagger.json; Please wait.
Any help is highly appreciated. Thanks in advance.
The GET /pet/findByStatus is generated in one of the examples:
github.com/zircote/swagger-php/.../Examples/petstore.swagger.io/controllers/PetController.php
The reason your snippet isn't working is because you're adding a property to an array type, which isn't supported.
To describe the contents of the array you'll need the #SWG\Items annotation:
...
* #SWG\Schema(
* type="array",
* #SWG\Items(
* type="object",
* #SWG\Property(property="firstname", type="string", example="Steven")
* )
* ),
...
I don't want page numbers on the first and last pages of my PDF so in my custom footer function I'm trying to compare the current page number to the total number of pages, which isn't working since $this->getAliasNbPages(); returns a string (something like "{ptp)"} which cannot be converted to an integer.
How do I get the total number of pages as an integer or otherwise find out if the current page is the last?
You can use
$this->getNumPages();
/**
* Reset pointer to the last document page.
* #param $resetmargins (boolean) if true reset left, right, top margins and Y position.
* #public
* #since 2.0.000 (2008-01-04)
* #see setPage(), getPage(), getNumPages()
*/
public function lastPage($resetmargins=false) {
$this->setPage($this->getNumPages(), $resetmargins);
}
/**
* Get current document page number.
* #return int page number
* #public
* #since 2.1.000 (2008-01-07)
* #see setPage(), lastpage(), getNumPages()
*/
public function getPage() {
return $this->page;
}
/**
* Get the total number of insered pages.
* #return int number of pages
* #public
* #since 2.1.000 (2008-01-07)
* #see setPage(), getPage(), lastpage()
*/
public function getNumPages() {
return $this->numpages;
}
originally from tcpdf.php you can find it all there